GC26-3841-3 
File No. S370-30 



Systems OS/VS2 Access Method Services 

Release 3.8 



This publication was produced using the 
IBM Document Composition Facility 

(program number 5748-XX9) 
and the master was printed on the 
IBM 3800 Printing Subsystem. 



Fourth Edition (October 1980) 

This is a major revision of, and makes obsolete, GC26-3841-2. 

This edition applies to Release 1.0 of Data Facility/Device 
Support, Program Product 574Q-AM7, as well as to Release 3.8 of 
0S/VS2 MVS, and to any subsequent releases until otherwise 
indicated in new editions or technical newsletters. 

The changes for this edition are summarised under "Summary of 
Amendments" following the preface. Specific changes are 
indicated by a vertical bar to the left of the change. These 
bars will be deleted at any subsequent republication of the page 
affected. Editorial changes that have no technical significance 
are not noted. 

Changes sre periodically made to the information herein; before 
using this publication in connection with the operation of IBM 
systems, consult the latest IBM Svstem/370 and 4300 Processors 
Bi bl i ography , 6C20-0001, for the editions that are applicable 
and current. 

It is possible that this material may contain reference to, or 
information about, IBM products (machines and programs), 
programming, or services that are not announced in your country. 
Such references or information must not be construed to mean 
that IBM intends to announce such IBM products, programming, or 
services in your country. 

Publications are not stocked at the address given below; 
requests for IBM publications should be made to your IBM 
representative or to the IBM branch office serving your 
locali ty . 

A form for reader's comments is provided at the back of this 
publication. If the form has been removed, comments may be 
addressed to IBM Corporation, P.O. Box 50020, Programming 
Publishing, San Jose, California, U.S.A. 95150. IBM may use or 
distribute any of the information you supply in any way it 
believes appropriate without incurring any obligation whatever. 
You may, of course, continue to use the information you supply. 

© Copyright International Business Machines Corporation 1975, 
1976, 1978, 1980 



ABOUT THIS BOOK 



This book describes the use of Access Method Services commands* 
a group of utility functions vital to Virtual Storage Access 
Method (VSAM). This publication provides VSAM information 
required to use Access Method Services to establish and maintain 
data sets. For information on VSAM data set and catalog format 
and structure, see Planning for Enhanced VSAM Under QS/VS , 
GC26-3842. For information on the use of VSAM macro 
instructions, VSAM optimization options, and various VSAM 
algorithms affecting performance* see QS/VS Virtual Storag e 
Access Method (VSAM) Programmer's Guide , GC26-3838. 

Readers of this book are presumed to have a background in 
programmi ng. 

This book has the following major divisions* 

• "Guide to Access Method Services," which lists functions and 
the Acdess Method Services commands used to perform them. 

• "Introduction," which provides an overview of Access Method 
Services, including general language considerations and the 
use of Time Sharing Option (TSO) and the 3850 Mass Storage 
System with VSAM and Access Method Services. Everyone who 
intends to use Access Method Services should first read this 
chapter. 

• "Data Security and Protection," which describes the recovery 
features of VSAM that are specified as options in Access 
Method Services commands. 

• "Creating and Cataloging Objects," which describes the use 
of the DEFINE command to define catalogs, data spaces, VSAM 
data sets, alternate indexes, paths, and page spaces, and to 
catalog generation data groups, aliases and nonVSAM data 
sets. 

• '"Building an Alternate Index," which describes the use of 
the BLDINDEX command to build an alternate index. An 
alternate index allows you to access a data set with a new 
set of key values. 

• "Modifying Catalog Information," which describes the use of 
the ALTER command to modify attributes in catalog entries. 

• "Displaying Catalog Information," which describes the use of 
the LISTCAT command to list catalog entries. 

• "Deleting Catalog Entries*" which describes the use of the 
DELETE command to delete catalog entries. 

• "Moving Entries*" which describes the use of the IMPORT and 
EXPORT commands to create a backup copy of a data set or to 
move a data set or user catalog between systems. 

• "Converting an OS Catalog's Entries to VSAM Catalog 
Entries*" which describes the use of the CNVTCAT command to 
convert OS catalog entries to VSAM catalog entries and merge 
them into a VSAM catalog. 

• "Restoring a Cluster's End-of-File Values*" which describes 
the use of the VERIFY command to ensure that the true 
end-of-f i le is reflected in the catalog. 

• "Restoring Catalog Entries After System Failure*" which 
describes the use of the LISTCRA* EXPORTRA, IMPORTRA* and 
RESETCAT commands to retrieve the contents of VSAM data sets 
after a VSAM catalog is damaged. 
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"Copying and Printing*" which describes the use of the REPRO 
command to copy and to reorganize data, and to convert data 
from i ndexed-sequential or sequential organization to VSAM 
organization and from VSAM organization to sequential 
organization* and to copy catalogs; and the use of the PRINT 
command to print VSAM and nonVSAM data sets. 

"Listing Tape Volumes Mounted at Checkpoint*" which 
describes the use of the CHKLIST command to list tape data 
sets that were open during a checkpoint. 

"Command Format*" which lists the Access Method Services 
commands and their format* describes the required and 
optional parameters* and specifies their abbreviations. 
There are examples with each command and a description of 
how the commands and their parameters were used. 

"Controlling Command Execution*" which describes the use of 
the IF, SET, and PARM commands to control command execution 
and to specify diagnostic aids and pri nted-output options. 

"Appendix A: Examples of Jobs Using Access Method Services 
Commands*" which describes how two or more Access Method 
Services commands can be used together to accomplish a task. 

"Appendix B: Interpreting LISTCAT Output Listings*" which 
provides information on the structure of LISTCAT output and 
shows sample output. 

"Appendix C- JCL DD Parameters to Take Care With," which 
describes JCL parameters that have either no effect in a 
VSAM environment or that have a negative effect. 

"Appendix D: Interpreting LISTCRA Output Listings*" which 
describes the format and uses of LISTCRA output. 

"Appendix E= Sample Output from CHKLIST," which shows a 
CHKLIST listing and explains its contents. 

"Appendix F« Command Reference Summary" which shows the 
format of each Access Method Services command* parameter 
abbreviations, and defaults. The commands are grouped 
together to allow you to remove these pages and use them as 
a quick reference guide. 

"Appendix Q' Invoking Access Method Services from a Problem 
Program*" which describes how Access Method Services may be 
dynamically invoked from a user's problem program. 

"Appendix H'» Changing the Attributes of the VSAM Master 
Catalog*" which describes how to apply new attributes to the 
VSAM master catalog; for example, changing it from 
nonrecoverable to recoverable. 

"Glossary," which defines terms relevant to Access Method 
Services and VSAM. 

"Index," which is a subject index to the book. 



REQUIRED PUBLICATIONS 



The reader should be familiar with information presented in the 
following publi cati ons: 

•■ OS/VS Virtual Storage Access Method (VSAM) Programmer's 
Gui de * GC26-3838, which provides information on VSAM 
optimization options and various VSAM algorithms affecting 
performance, macro instructions used. to process VSAM data 
sets, and how-to use an ISAM processing program to process < 
VSAM data set or an i ndexed-sequenti al data set that has 
been converted to VSAM format. 
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Planning for Enhanced VSAM Under OS/VS , GC26-3842, which 
includes information on the structure and contents of VSAM 
catalogs and data sets and also information on protecting 
VSAM catalogs and data sets. 

0S/VS2 MVS Utilities , GC26-3902, which describes the utility 
programs available for use with nonVSAM data sets on 0S/VS2 
systems. 

0S/VS2 MVS Data Management Services Guide , GC26-3875, which 
presents basic concepts such as access method, direct-access 
storage, and the distinction between data-set organisation 
and data-set processing. 

0S/VS2 JCL , GC28-0692, which describes the JCL parameters 
referred to in this publication. 

OS/VS Message Library: VS2 System Messages , GC38-1002, 
which provides a complete listing of the messages issued by 
Access Method Services in a VS2 system. 

Q5/VS2 System Programming Library? System Generation 
Reference , GC26-3792, which provides information necessary 
to install an MVS system control program. 



RELATED PUBLICATIONS 



The following publications contain information that is related 
to this publication? 



OS/VS Virtual Stora 
Advanced Applicat 



rage Access Method (VSAM)' Options for 

i ons , GC26-3819, which provides information 

plications of VSAM which the reader doesn't 




0S/VS2 Checkpoint/Restart , GC26-3877, which explains how to 
take checkpoints and to restart processing. 

Introduction to the IBM 3850 Mass Storage System (MSS) , 
GA32-0028, which introduces the storage devices and 
programming of the Mass Storage System. 

OS/VS Mass Storage System (MSS) Services' Reference 

Inf ormat i on , GC35-0017, which describes the Mass Storage 

System Access Method Services commands for the Mass Storage 

System. 

0S/VS2 System Programming Library: Data Management , 
GC26-3830, which describes how to use the PROTECT macro. 

0S/VS2 System Programming Library- Supervisor , GC28-0628, 
which describes the authorized program facility. 

QS/VS2 TSO Command Language Reference , GC28-0646, which 
describes TSO commands. 

0S/VS2 TSO Terminal User's Guide , GC28-0645, which describes 
commands available to the TSO user. 

0S/VS2 System Programming Library? TSO , GC28-0629, which 
describes the TSO facilities that can be influenced by the 
system programmer. 

0S/VS2 MVS TSO Command Package? User's Guide and Reference , 
SC28-0748, which describes the TSO facilities that can be 
influenced by the system programmer. 
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0S/VS2 Using OS Catalog Management with the Master Catalog 1 
CVOL Processor , GC35-0010, which describes the use of 
control volumes. 

0S/VS2 Virtual Storage Access Method (VSAM) Logic , 
SY26-3825, which describes the functional operation of VSAM 
(Record Management* Open, Close, End-of-Volume, and Control 
Block Manipulation commands). 

0S/VS2 Catalog Management Logic , SY26-3826, which describes 
the functional operation of VSAM Catalog Management. 

0S/VS2 Access Method Services Logic , SY35-0010, which 
describes the functional operation of Access Method Services 
Programs. 

0S/VS2 MVS Resource Access Control Facility (RACF) General 
Information Manual , GC28-0722, which contains initial 
planning information for RACF. 

0S/VS2 Resource Access Control Facility (RACF) Command 
Language Reference , SC28-G733, which describes the syntax 
and function of RACF commands. 



0S/VS2 System Programming Library : Debugging Handbook Volume 
1, GC28-0708, and Volume 2, GC28-0709,. which describes 
debugging procedures. (Both manuals may be ordered using 
GB0F-8211.) 



NOTATION CONVENTIONS 



A uniform system of notation describes the format of Access 
Method Services commands. This notation is not part of the 
language; it simply provides a basis for describing the 
structure of the commands. 

The command-format illustrations in this book use the following 
conventions* 



Brackets C ] indicate an optional parameter. 

Braces { } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 

Items separated by a vertical bar represent alternative 
items. No more than one of the items may be selected. 

An ellipsis ... indicates that multiple entries of the type 
immediately preceding the ellipsis are allowed. 

Other punctuation (parentheses, commas, spaces, etc.) must 
be entered as shown. A space is indicated by b. 

Boldface type indicates the exact characters to be entered. 
Such items must be entered exactly as illustrated (in upper 
case, except in TSO). 

Lowercase type in the command format specifies fields to be 
supplied by the user. 

Underscored type indicates a default option. If the 
parameter is omitted, the underscored value is assumed. 

A b in the command format indicates a blank must be present 
before the next parameter. 
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SUMMARY OF AMENDMENTS 



O S/VS2 MVS DATA FACILITY/DEVICE SUPPORT RELEASE 1.0 PROGRAM NUMBER 5740-AM7 

The system residence volume serial number and/or device type can 
now be changed without having to recatalog all the non-VSAM data 
sets on the volume. See the changes for DEVICETYPES and VOLUMES 
parameters in the "Command Format" chapter, "DEFINE NONVSAM." 

The size of an allocation unit for the IBM 3380 and IBM 3375 is 
included in "Creating and Cataloging Objects," section "How 
Space Is Assigned to a Catalog." 

Editorial changes have been made throughout this book; service 
changes are noted by a revision bar in the left margin. 



JULY 1978 



Command parameters have been arranged in alphabetic order. 

•Appendix F has been completely revised. It is now a reference 
summary showing the syntax of each command, parameter 
abbreviations, and defaults. 

Numerous editorial and service changes have been made throughout 
the book. 



0S/VS2 MVS SUPERVISOR PERFORMANCE tt2 (VS2. 03.807) 

AUXILIARY STORAGE MANAGER (ASM) REDESIGN 

SWAP space data sets can now be defined and Preformatted. Also, 
a new integrity attribute has been added to both SWAP and PAGE 
spaces. 

RESOURCE ACCESS CONTROL FACILITY CRACF) 

Changes are included to support protection of VSAM data sets 
through RACF. 



OS/VS2 MVS DATA MANAGEMENT (VS2.03.808) 

EXTENDED CVOL SUPPORT 

In 0S/VS2 MVS Release 2, the VSAM catalog replaced the system 
master catalog and support of OS CVOLs was limited to a subset 
of what had been provided in 0S/VS2 SVS Release 1. Extended CVOL 
support provides a CVOL function that is equivalent to SVS while 
retaining the VSAM master catalog as the only system master 
catalog. This support required that changes be made to the 
section "VSAM's Use of Catalogs" and the chapter "Converting an 
OS Catalog's Entries to VSAM Catalog Entries." 
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RESETTING A CATALOG 



A new Access Method Services command, RESETCAT, has been added 
to support recoverable catalogs. The new command will allow you 
to reset your VSAM catalog to the level of its owned volumes. 
That is, if the catalog or any of its volumes become damaged, 
RESETCAT can be used to synchronize a catalog to a restored (not 
current) level version of a volume. Or, if the catalog has to be 
restored or reloaded, its entries can be changed to reflect the 
current level of its volumes with RESETCAT. The new sections 
"Resetting a Catalog" and "RESETCAT" have been added to describe 
and define parameters for this command. 
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LISTCAT Format 



The format of LISTCAT output has been modified to improve 
readabi li ty . 



Miscellaneous Topics 



Two new appendixes have been added. They are: Appendix G : 
Invoking Access Method Services from a Problem Program, and 
Appendix H : Changing the Attributes of the VSAM Master Catalog. 

All Access Method Services command formats, parameter 

descriptions, and examples have been moved to a new chapter : 

Command Format. In the new chapter, commands ar& arranged in 
alphabetical order. 

Information relating to such topics as VSAM Data Structure, How 
Data is Physically Stored, Types of VSAM Data Sets, VSAM Catalog 
Structure, Performance Optimization, and Data Integrity has been 
removed from this book. The information removed can be found in 
other VSAM publications. 



INDEPENDENT COMPONENT RELEASE 



Following is a summary of major changes to Access Method 
Services for the release of enhanced VSAM as an independent 
component under 0S/VS2. 



Alternate Index 



The alternate index allows you to access data records using a 
key field other than the key field established when the data set 
was defined (for key-sequenced VSAM data sets), and to access 
the data records of an entry-sequenced data set with a key 
field. 



Reusable Data Set 



The reusable data set is an attribute that can be applied to 
VSAM entry sequenced, key sequenced, relative-record and 
alternate index data sets. This attribute allows the data set to 
be used for temporary storage of data. Whenever a reusable VSAM 
data set is opened, its high-used RBA can be reset to zero. 
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Spanned Records 



Data records in VSAM data sets can be larger than one control 
interval, and are contained in two or more control intervals. 



Relative-Record Data Set 



The relative-record data set is a VSAM data set whose records 
are fixed-length and are sequenced according to record number. 



VSAM Volume Cleanup 



The VSAM volume cleanup process allows you to erase VSAM data 
from a volume's VTOC and reset the VTOC's format-4 DSCB to show 
system ownership of the volume. The process is to be used when a 
system or device failure occurs that damages the volume's 
information in its VSAM catalog (that is, the VSAM catalog that 
owns the volume) . 



VSAM Catalog Cleanup 



The VSAM catalog cleanup process allows you to delete a VSAM 
catalog without first deleting each of its cataloged entries. 
You can use this function to remove an unwanted catalog from 
your system. (Certain safeguards prevent indiscriminate use of 
the f uncti on. ) 



Record Replacement (During REPRO) 



You can merge two data sets so that, when duplicate records are 
encountered, the older record (that is, the one in the target 
data set) is replaced with the newer record (the one in the 
source data set). 



Catalog Recovery 



Three new Access Method Services commands support recoverable 
catalogs: LISTCRA, EXPORTRA, and IMPORTRA. The catalog recovery 
function allows you to repair damaged entries in a VSAM catalog 
when a system failure occurs. 



Catalog Recovery Area 



Copies of each catalog record s>r& maintained (on the volume 
containing the catalog entry's data records) in an area called 
the catalog recovery area. The catalog recovery area is built 
and maintained only for recoverable catalogs, and is used to 
recover from damaged catalog entries. 



Exception Exit Routine 



You can write an I/O error handling routine, called the 
exception exit routine, that is tailored for a cluster's or 
alternate index's data or index component, and which is called 
before the user program's SYNAD routineggets control. 



Miscellaneous Topics 



The KEYS and RECORDSIZE parameters of the DEFINE CLUSTER command 
have been modified so that a default value exists for them. The 
ALTER command's parameter set now includes the KEYS and 
RECORDSIZE parameters. 

You can import an exported object into a predefined object. 
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You can specify blocksize for exported and imported objects. 

The dname subparameter of the CATALOG parameter has been omitted 
from the syntax of those commands that no longer require its 
specification. If you specify dname, it will be ignored. 
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GUIDE TO ACCESS METHOD SERVICES 



Figure 1 shows a list of tasks that Access Method Services 
commands can be used to perform. The left-hand column shows 
tasks that you might want to perform. The middle column more 
specifically defines the tasks. The right-hand column shows the 
commands that can be used to perform each task. 



Operation 

Alter the information in a catalog entry 
Attach a user catalog to the master catalog 

Backup a VSAM data set 

a nonVSAM data set 
a VSAM catalog 

Build an alternate index 

a generation data group 

Catalog a VSAM data set 

a nonVSAM data set 

Change a data set's description in the 

catalog the device type of the volume 
on which the catalog resides 

Connect a user catalog to a master catalog 
an OS/VS CVOL to a master catalog 

Convert a data set to VSAM format 

a VSAM data set to sequential format 

OS/VS CVOL entries to VSAM 
catalog entries 

Copy a data set or catalog 

Create a backup copy of a data set 
a catalog 

an alias for a nonVSAM data set 
an alias for a VSAM data set 
a VSAM data set 
an alternate index 

the relationship between an alternate 
index and its base cluster 
a generation data group 

a generation data set 

a page space 

a VSAM data space 

a catalog entry for a nonVSAM 

data set 

Define (see above entries for Create) 

Figure 1 (Part 1 of 3). Tasks and Commands 



Command 

ALTER 

DEFINE USERCATALOG or 
IMPORT CONNECT 

EXPORT or REPRO 

REPRO 

REPRO 

DEFINE ALTERNATEINDEX and 

BLDINDEX 

DEFINE 

GENERATIONDATAGROUP 

DEFINE CLUSTER and 
DEFINE ALTERNATE INDEX 
DEFINE NONVSAM 

ALTER 
REPRO 



IMPORT CONNECT 
DEFINE NONVSAM 

REPRO 
REPRO 
CNVTCAT 



REPRO 

REPRO or EXPORT 

DEFINE USERCATALOG 

DEFINE ALIAS 

DEFINE PATH 

DEFINE CLUSTER 

DEFINE ALTERNATEINDEX and 

BLDINDEX 

DEFINE PATH 

DEFINE 

GENERATIONDATAGROUP 
DEFINE NONVSAM 
DEFINE PAGESPACE 
DEFINE SPACE 
DEFINE NONVSAM 



Guide to Access Method Services 



Operation 

Delete 



Di sconnect 
Di splay 

Enter 
Export 

Import 

List 



Load 
Modi fy 
Move 



Password 
Protect 



Print 
Recover 



a user catalog 

an al ias 

&n alternate index and its paths 

a path 

any type of catalog entry 

a VSAM data set 

a VSAM data space 

a generation data group 

a nonVSAM data set 
a page space 

a user catalog 

a catalog's contents 

a catalog recovery area's contents 

a nonVSAM data set in a catalog 

a user catalog 
a VSAM data set 

a user catalog 
a VSAM data set 

a password 

a data set's contents 

contents of a catalog or of a catalog 

entry 

contents of a catalog recovery area 

tapes mounted at a checkpoint 

records into a data set 
an alternate index 

a data set's description in the 
catalog 

a catalog to another system 

a VSAM data set to another system 

a nonVSAM data set to another 
system 

establish for a VSAM data set 

alternate index 

path 

catalog 

page space 

modify an existing password, or add 

a password to an existing catalog 

entry 

delete a password 

1 i st passwords 

a data set 

from a processing-program failure 
from a catalog failure 



command 

DELETE USERCATALOG 

DELETE ALIAS 

DELETE ALTERNATEINDEX 

DELETE PATH 

DELETE 

DELETE CLUSTER 

DELETE SPACE 

DELETE 

GENERATIONDATAGROUP 

DELETE NONVSAM 

DELETE PAGESPACE 

EXPORT DISCONNECT 

LISTCAT 
LISTCRA 

DEFINE NONVSAM 

EXPORT DISCONNECT 
EXPORT or EXPORTRA 

IMPORT CONNECT 
IMPORT or IMPORTRA 

LISTCAT 

PRINT 

LISTCAT 

LISTCRA 
CHKLIST 

REPRO 
BLDINDEX 

ALTER 



EXPORT DISCONNECT and 

IMPORT CONNECT 

EXPORT and 

IMPORT 

REPRO 



DEFINE CLUSTER 

DEFINE ALTERNATEINDEX 

DEFINE PATH 

DEFINE USERCATALOG or 

DEFINE MASTERCATALOG 

DEFINE PAGESPACE 

ALTER 



ALTER 
LISTCAT 

PRINT 

VERIFY 
LISTCRA and 
EXPORTRA and 
IMPORTRA 
RESETCAT 



Figure 1 (Part 2 of 3). Tasks and Commands 
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Operation 

Release 

Rename 

Reproduce 

Restore 

Uncatalog 
Unload 



a user catalog from the master 
catalog 

a data set 

a VSAM or nonVSAM data set 

a data set's end-of-file information 
a catalog entry and/or the contents 
of its object 

a data set 

a data set or catalog 



a VSAM data set's end-of-file 
i ndi cators 



Veri fy 

Figure 1 (Part 3 of 3). Tasks and Commands 



Command 

EXPORT DISCONNECT 

ALTER 

REPRO 

VERIFY 

EXPORTRA and 
IMPORTRA 
RESETCAT 

DELETE 

REPRO 

VERIFY 
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INTRODUCTION 



Access Method Services is a service program that is used with 
VSAM (Virtual Storage Access Method) to establish and maintain 
catalogs and data sets. If you plan on using VSAM, or if you are 
responsible for maintaining the system catalog, you must use 
Access Method Services commands. 

This chapter introduces the commands available through Access 
Method Services, provides the background information about VSAM 
that is required to establish and maintain data sets and 
catalogs, and briefly describes the use of the Time Sharing 
Option (TSO) with VSAM and Access Method Services. 



ACCESS METHOD SERVICES COMMANDS 



Access Method Services enables you to define a VSAM data set and 
load records into it, convert a sequential or an 
i ndexed-sequent i al data set to the VSAM format, list VSAM 
catalog information or data-set records, copy a data set for 
reorganisation, create a backup copy of a data set or catalog, 
convert an OS CVOL's entries to VSAM catalog entries, and make a 
data set portable from one operating system to another. 

The user invokes Access Method Services functions by issuing a 
command and specifying its parameters. The user can execute the 
IDCAMS program and include the command and its parameters as 
input to the program. The user can also call the IDCAMS program 
from within another program and pass the command and its 
parameters to the IDCAMS program. TSO (Time Sharing Option) 
users can execute Access Method Services functional commands 
from the TSO terminal as though they were TSO commands. 

There are Access Method Services commands for* 

Defining, altering, and deleting data sets 

Listing catalog entries 

Copying and printing data sets 

Constructing alternate indexes for VSAM data sets 

Moving catalogs and data sets from one operating system to 
another 

Aiding in recovery from damage to data sets or catalogs 

Converting an OS catalog's entries to VSAM catalog entries 

Listing tape volumes that were mounted at the time of a 
checkpoi nt 

Controlling command execution by testing or setting 
condition codes 

Establishing diagnostic-aids and pri nted-output options 

There are two types of Access Method Services commands? 
functional commands that are used to request the actual 
work — for example, defining a data set or listing a catalog — and 
modal commands that allow the conditional execution of 
functional commands. TSO users are allowed to use only the 
functional commands. 
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FUNCTIONAL COMMANDS 

The functional commands are! 



ALTER* which is used to alter previously defined catalog 
entri es. 

BLDINDEX, which constructs alternate indexes for existing 
data sets. 

CHKLIST, which is used to identify tape volumes mounted when 
a checkpoint was taken. 

CNVTCAT, which is used to convert entries in an OS CVOL 
(control volume) into entries in a VSAM catalog. 

DEFINE, which is used to create catalog entries for data 
sets, catalogs, and space that VSAM is to allocate from. 

DELETE, which is used to delete catalog entries. 

EXPORT, which is used to create a copy of a VSAM data set 
for backup or to make a data set or user catalog portable so 
that it can be used on another system. 

EXPORTRA, which retrieves VSAM data sets and catalog entries 
that are no longer accessible from a VSAM catalog. 

IMPORT, which is used to read a backup copy of a VSAM data 
set or to make a data set or catalog that was previously 
exported from one system available for use in another 
system. 

IMPORTRA, which returns VSAM data sets and catalog entries 
to an accessible condition. 

LISTCAT, which is used to list catalog entries. 

LISTCRA, which is used to diagnose suspected problems in 
VSAM catalogs. 

PRINT, which is used to print VSAM, ISAM, or SAM data sets. 

REPRO, which is used to copy data sets, to convert 
sequential and i ndexed-sequent i al data sets to VSAM format, 
to convert VSAM and i ndexed-sequent i al data sets to 
sequential format, to back up a VSAM catalog, to read a 
backup copy of a VSAM catalog, and to copy VSAM catalogs. 

RESETCAT, which synchronizes a catalog to the level of its 
owned volumes. 

VERIFY, which is used to cause a catalog to correctly 
reflect the end of a data set after an error occurred in 
closing a VSAM data set that may have caused the catalog to 
be incorrect. 

The functional commands that can be used on nonVSAM data sets 
include DEFINE, ALTER, DELETE, LISTCAT, CNVTCAT, REPRO, and 
PRINT. 

The functional commands that can be used on page spaces include 
DEFINE, DELETE, ALTER, and LISTCAT. 

All functional commands except CHKLIST can be used when you 
execute Access Method Services at a TSO terminal. 
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MODAL COMMANDS 

The modal commands* ones that control command execution and 
establish options* are: 

• IF, which tests a condition code and executes according to 
the results of the test. IF is followed by THEN and ELSE 
clauses which specify alternative actions. 

• DO-END, which denote the beginning and ending of a command 
sequence. 

• SET, which changes condition codes. 

• PARM, which specifies diagnostic-aids and pri nted-output 
options. 

LANGUAGE CONSIDERATIONS 

All Access Method Services commands have this general structures 

COMMAND parameters ... terminator 

COMMAND specifies the type of service requested. The parameters 
further describe the service requested. Terminator indicates the 
end of the command statement. 

Commands can begin at or to the right of the left margin. The 
default margins are 2 and 72 for batch processing jobs. Commands 
are separated from their parameters by one or more separators, 
that is, one or more blanks, commas, or comments. Comments are 
strings of characters surrounded by a /* and an */ . Comments can 
contain any characters you desire except an '*/*. 

Many of the commands can be abbreviated. The abbreviations that 
are allowed are listed in the discussion of each command as well 
as in Appendix F. Restrictions that apply to abbreviations under 
TSO are described in "Time Sharing Option (TSO)." 



Parameter Set 



A parameter can be either a positional parameter or a keyword 
parameter. A positional parameter is characterized by its 
position in relation to other parameters. In Access Method 
Services, positional parameters are always required. A keyword 
parameter is a value preceded by a specific character string. 
For example, in : 

VOLUME (25DATA) 

VOLUME is a keyword that indicates that the value 25DATA is a 
volume serial number. 

A keyword parameter might have a set of subparameters. The 
subparameters must follow the same rules as parameter sets in 
general. When the subparameters are positional, the first 
subparameter is always required and the second may be optional 
(that is, you cannot specify the second subparameter without 
also specifying the first). 

Many of the keywords may be abbreviated. The abbreviations 

permitted are listed with each parameter as well as in Appendix 

F. Some keywords are plural in form; they can also be coded in 
the singular form. 

As a group, positional parameters must always appear first in a 
parameter set. Keyword parameters always follow any positional 
parameters. The order of keyword parameters is not important. 

A parameter or subparameter can consist of a list of similar 
items. Positional parameter lists must be enclosed in 
parentheses unless the list contains only one item. The 
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parentheses can be preceded and followed by blanks, commas, or 
comments. For. example 2 

DELETElentryname C...1) 

indicates that if more than one entry is to be deleted, the list 
of entrynames must be enclosed in parentheses. However, if only 
one entryname is specified, the parentheses are not required. 

An item in a list can be a parameter set itself. Each such item, 
as well as the list of items, is enclosed in parentheses. Given*- 

OBJECTS( (entryname NEWNAME (newname) ) . . . ) 

the following are valid* 

OBJECTSC - 

ENTRY1 NEWNAME(NEWNAMEl)) 

OBJECTSC - 

(ENTRY1 NEWNAME(NEWNAMED) - 
(ENTRY2 NEWNAMECNEWNAME2))) 

In the first case, only one entry is to be renamed. The 
entryname and its new name are enclosed in parentheses. In the 
second case, each entryname and its new name are enclosed in 
parentheses and the entire list is enclosed in parentheses. 

All parameters and subparameters must be separated from one 
another by one or more separators (commas, blanks, or comments). 
The only exception is that parameters that immediately follow a 
subparameter set that is enclosed in parentheses do not need to 
be separated from the closing parenthesis. 

The values you specify in the parameters can be surrounded by 
separators. Some values can be longer than a single record. When 
a value is longer than a single record, you indicate that it is 
continued by coding a plus sign (+) followed only by blanks or a 
comment. The first nonseparator character found in a record 
following the plus sign is treated as a continuation of the 
value. 

A value cannot contain commas, semicolons, blanks, parentheses, 
or slashes unless the entire value is enclosed in single 
quotation marks. A single quotation mark in a field enclosed in 
single quotation marks must be coded as two single quotation 
marks. 

In some parameters it is necessary to specify a password 
following the name of a catalog entry or the name of a JCL DD 
statement. You do this by coding the name, a slash, and the 
password. The slash can be surrounded by separators. For 
example : 

DELETE PAYROLL/CTLGPAY 

specifies the password CTLGPAY for the data set PAYROLL. 

When you specify a password following a name, you must remember 
the convention for entering commands. If you code : 

MYNAME/KWORD*/ 

MYNAME is treated as a name followed by the comment WORD. If you 
want *W0RD*/ to be the password, you code either 1 

MYNAME/ '*W0RDX/» 



MYNAME/ KWORD*/ 

Notice that the second example contains a blank after the first 
slash that separates the name from the password. 

Introduction 



Continuing Commands 



Commands can be continued on several records or lines. Each 
record or line except the last must have a hyphen or a plus sign 
as the last nonblank character before or at the right margin. A 
hyphen indicates continuation of the command. A plus sign 
indicates continuation of the command and continuation of a 
value within the command. These two types of continuation are 
shown in the example below : 

DELETE - 
(ENTRY1 - 
ENTRY2 - 
ENTR+ 

Y3) - 
NONVSAM 

Blank records or records ending with complete comments must end 
with a continuation mark when they appear in the middle of a 
command and when they appear preceding or following the THEN and 
ELSE clauses of an IF command. Records ending with partial 
comments must always end with a continuation mark. Also, 
remember that only blank characters may appear between a 
continuation mark and the end of the record. 

Note: The DO-END sequence does not require continuation 
characters. 



continuation cautions 



The continuation rules must be used cautiously when modal 
commands, comments, or blank records appear in the input stream. 
Blank records or records ending with complete comments must end 
with a continuation mark when these types of records appear in 
the middle of a command or when they appear preceding or 
following the THEN and ELSE clauses of an IF command. Records 
ending with partial comments must always end with a continuation 
mark. 

You must be careful when continuing modal commands so that you 
don't inadvertently specify a null command. For information on 
null commands, see "Null Commands." 

Remember that only blanks can appear between a continuation mark 
and the end of the record. 

Note? The DO-END sequence does not require continuation 
characters; if they are used, they may be taken as a null 
command or cause unpredictable results. 

The following examples show common continuation errors-' 

• IF LASTCC = - 
THEN 

LISTCAT 

A continuation mark (hyphen) is missing after the THEN 
keyword. A null command is assumed after the THEN keyword, 
and the LISTCAT command is unconditionally executed. 

• IF LASTCC = - 
THEN - 

REPRO ... 

/^ALTERNATE PATH*/ 
ELSE - 
PRINT . .. 

Because no continuation mark (hyphen) follows the comment, a 
null command is assumed. The ELSE keyword will not match up 
with the THEN keyword. Note the correct use of the 
continuation marks on the other records. 



• IF LASTCC = - 
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Terminator 



THEN - 
REPRO . . . 
ELSE - 

PRINT . . . 

Because a blank line with no continuation mark (hyphen) 
follows the ELSE keyword, the ELSE becomes null and the 
PRINT command is unconditionally executed. 

PARM TEST ( - /XCOMMENT*/ 
TRACE) 

The PARM command will not be continued onto the second 
record because characters other than blanks appear between 
the continuation mark (hyphen) and the end of the record. 

PARM TEST ( TRA+ 
/*FIELD CONTINUATION*/ 
CE) 

The end of the PARM command i s found after the second record 
because no continuation was indicated. The command is 
rejected. 



The terminator indicates the end of the command. The terminator 
can be either an end of command condition (that is, no 
continuation mark) or a semicolon. If you use the semicolon as 
the terminator, the semicolon cannot be enclosed in quotation 
marks or embedded in a comment. Everything to the right of the 
semicolon is ignored. If there is information to the right of 
the semicolon that is continued to another record, all of the 
information including the continued information is ignored. 

For example, if you coded : 

PARM TEST (TRACE); PARM - 
GRAPHICS (CHAIN(TN))/*COMMENT*/»- 
PRINT ... 
REPRO ... 

Characters following the semicolon terminator are ignored. The 
continuation mark (hyphen) at the end of the second record 
causes the PRINT command to also be ignored. The first PARM 
command and the REPRO command are the only commands that are 
recogni zed. 



JCL AND DYNAMIC ALLOCATION 



Access Method Services commands deal with both data sets and 
volumes which must be identified when used. The following is a 
summary of the data set and volume identification requirements: 

• A data set must be identified when it is actually accessed. 
The following commands require that a specific data set or 
data sets be identified. 

ALTER (when altering a member name in a partitioned data 
set) 

BLDINDEX 

DELETE (when the ERASE option is invoked, when deleting 
a member of a partitioned data set) 

EXPORT 

IMPORT 
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PRINT 

REPRO 

VERIFY 

* A volume or volumes must be identified when it is necessary 
for VSAM to access the Volume Table of Contents (VTQC), 
allocate or release space using OS/VS DADSM functions, or 
access a catalog recovery area (see the section "Catalog 
Recovery" for information on this option). The following 
commands require volume identification* 

ALTER (for recoverable catalogs, for VTOC access in 
renaming a nonVSAM or VSAM unique data set) 

DEFINE (for recoverable catalogs, for space allocation 
in defining catalogs, VSAM space, and VSAM unique data 
sets) 

DELETE (for recoverable catalogs, for space deallocation 
in deletion of catalogs, VSAM space, and VSAM unique 
data sets, for deletion of nonVSAM data sets) 

Other commands such as EXPORTRA, IMPORTRA, LISTCRA, and RESETCAT 
require volume identification for specific purposes. These 
requirements are covered in the discussion of each command. 

A VSAM data set or volume can be identified through JCL or by 
the data-set name or volume serial number within the command 
that requires the data set or volume for its execution. If JCL 
is not used, the data set or volume is dynamically allocated, as 
requi red. 

In order to dynamically allocate a VSAM data set, the data-set 
name must exist and be cataloged. The catalog that contains the 
entry must be either a user catalog identified with a JOBCAT or 
STEPCAT DD statement, a user catalog whose name or alias is the 
first qualifier of the qualified data-set name, or the master 
catalog. 

In order to dynamically allocate a nonVSAM dataset, the data set 
name must exist and must be cataloged. The catalog that contains 
the entry must be either a VSAM user catalog identified with a 
JOBCAT or STEPCAT DD statement, a VSAM user catalog or OS CVOL 
whose name or alias is the first qualifier of the qualified 
data-set name, or the master catalog. 

Access Method Services dynamically allocates VSAM and nonVSAM 
data sets with a disposition of OLD. 

When a user catalog is identified by name in an Access Method 
Services command (using the CATALOG parameter) or when VSAM 
determines that a specific user catalog must be accessed, the 
user catalog is dynamically allocated if it has not been 
identified with a JOBCAT or STEPCAT DD statement. 

In order to dynamically allocate a volume, it must already be 
mounted as permanently resident or reserved. The PRIVATE and 
PUBLIC use attributes should be carefully considered when you 
mount a volume. 

When a JCL DD statement is used to identify a data set, the 
following information must be included on the DD statement. 

• The data-set name 

• The unit and volume serial number(s), if the data set is not 
cataloged 

• The disposition 
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• For VSAM data sets, the AMP='AM0RG' parameter is required if 
the JCL also supplies unit and volume serial number 

i nf ormat i on 

For example, the two DD statements shown below demonstrate two 
different methods by which you can describe and allocate a VSAM 
data set? 

//VSAMDS1 DD DSN=VSAM.DATA.SET1,DISP=0LD 
//VSAMDS2 DD DSN=VSAM. DATA . SET2, VOL=SER=VSER01 , 
// UNIT=3330,DISP=OLD,AMP='AMORG' 

Access Method Services does not provide specific protection for 
data sets in a shared environment. Therefore, you should specify 
DISP=0LD on the DD statement for any data set which could be 
accessed improperly in a shared environment. 

Access Method Services uses default buffering for VSAM data 
sets; that is, the buffer space value contained in the data 
set's catalog entry. You may wish to override this value using 
the BUFND, BUFNI, or BUFSP subparameter of the AMP parameter 
( see OS/VS Virtual Storage Access Method (VSAM) Programmer's 
Gui de for information on these parameters). 

To identify and allocate a volume, the following information 
must be included 1 

• The volume serial number 

• The unit 

For example, the DD statement shown below identifies and 
allocates a VSAM volume 1 

//VOLDD DD VOL=SER=VSERQ1,UNIT=3330,DISP=OLD 

Concatenated DD statements are supported under circumstances 
explicitly specified in the remainder of this publication. 

The section "JOBCAT and STEPCAT DD Statements" contains a 
description of the DD statements required for user catalogs. 

Certain Access Method Services commands use nonVSAM data sets. 
They are'* EXPORT, IMPORT, EXPORTRA, and IMPORTRA. The examples 
provided for each command in the section "Command Format," as 
well as the examples in Appendix A, show the DD statements for 
the required nonVSAM data sets. 

If the Access Method Services processor encounters a condition 
which requires it to abort a job, it takes a snap dump of 
virtual storage. An AMSDUMP DD statement is required to obtain 
the snap dump; for example, 

//AMSDUMP DD SYS0UT=A 

If you do not supply an AMSDUMP DD statement and the processor 
encounters a condition requiring the job to be aborted, it 
produces an abbreviated dump only. 



OUTPUT DATA SETS 



The normal output data set for listing is SYSPRINT. The default 
parameters of this data set are : 

• Record format: VBA 

• Logical record length? 125, that is, 121+4 

• Blocksize: 629, that is, 5x(121+4)+4 

Print lines are 121 bytes in length. The first byte is the ANSI 
control character. The minimum specifiable LRECL is 121 
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(U-format records only). If a smaller size is specified, it is 
overridden to 121. 

It is possible to alter the above defaults through specification 
of the desired values in the DCB parameter of the SYSPRINT 
statement. The record format* however, cannot be specified as F 
or FB. If you do specify either one, it is changed to VBA. 

In several commands you have the option of specifying an 
alternate output data set for listing. If you do specify an 
alternate, you must specify DCB parameters in the referenced DD 
statement using the attributes described above. When specifying 
an alternate output data set, you should not specify F or FB 
record formats. Note, however, that JCL statements, system 
messages, and job statistics ar& written to the SYSPRINT output 
device, not to the alternate output data set. "Appendix D 
Interpreting LISTCRA Output Listings" shows an example of the 
use of an alternate output data set. 



INVOKING ACCESS METHOD SERVICES 



When you want to use an Access Method Services function, you 
invoke the Access Method Services processor. The processor 
decodes your request (that is, the list of commands and 
parameters you supply) one command at a time, then calls the 
appropriate functional routines to perform all services required 
by that command. 

There are three ways you can invoke the Access Method Services 
processor ' 

• As a job or jobstep 

• From a TSO terminal 

• From within your own program. (See "Appendix G : Invoking 
Access Method Services from a Problem Program.") 

If you want more details on the structure and operation of 
Access Method Services in an 0S/VS2 system, see QS/VS2 Access 
Method Services Logic . 



AS A JOB OR JOBSTEP 



You can use job control language (JCL) statements to invoke the 
Access Method Services processor. The examples that illustrate 
each command's use invoke the processor with JCL statements. You 
identify the Access Method Services processor with PGM=IDCAMS. 

//YOURJOB JOB YOUR INSTALLATION'S J0B=ACC0UNTING DATA 

//JOBCAT DD DSNAME=YOUR-. CATALOG, DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=ANOTHER. CATALOG, DISP=SHR 

//SYSPRINT DD SYSQUT=A 

//SYSIN DD * 

Access Method Services commands and their parameters 

/* 

* //YOURJOB is required. The JOB statement describes your job 
to the 0S/VS2 system. Your installation might require you to 
supply user identification, accounting, and authorization 
information with the JOB statement's parameters. 

• //JOBCAT is optional. The JOBCAT DD statement identifies a 
user catalog that can be used by each of the job's steps. 
Because the master catalog is always open and available to 
all jobs on the system, you should not identify it with a 
JOBCAT DD statement. 
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//STEP1 is required (that is, an EXEC statement is 
required). The EXEC statement invokes the Access Method 
Services processor to decode and process the input 
statements (that is, the Access Method Services commands and 
parameters contained in the SYSIN data set). You can use the 
PARM operand of the EXEC statement to pass parameters to the 
Access Method Services processor. See the description of the 
PARM command in the chapter "Controlling Command Execution" 
for an explanation of the options you can specify. 

//STEPCAT is optional. The STEPCAT DD statement identifies a 
user catalog that can be used when processing the jobstep. 
If user catalogs are identified with JOBCAT and STEPCAT DD 
statements, only the catalog(s) identified with the STEPCAT 
DD statement and the master catalog ar& used with the 
jobstep. Because the master catalog is always open and 
available to all jobs on the system, you should not identify 
it with a STEPCAT DD statement. 

//SYSPRINT is required. The SYSPRINT DD statement identifies 
the output device (usually a printer in a batch job) that 
Access Method Services sends messages and output information 
to. (See "Output Data Sets" for more details on how to 
describe an output device other than SYS0UT=A.) 

//SYSIN is required. The SYSIN DD statement identifies the 
source of the input statements. An input statement, to 
Access Method Services, is a functional or modal command and 
its parameters. When you code SYSIN DD *, you identify the 
statements immediately following as input. 

The last input statement may be followed by a delimiter 
statement, which has '/*' in the first two columns. The 
restrictions that apply to all Access Method Services 
commands are described in the section "Language 
Considerations," above. 



FROM A TSO TERMINAL 



When you use the Time Sharing Option (TSO) to process your data, 
you can invoke Access Method Services from your TSO terminal. 
Each time you issue an Access Method Services command as a TSO 
command, TSO builds the appropriate interface information and 
invokes Access Method Services. 

You can issue one command at a time. Access Method Services 
processes the command completely before TSO allows you to 
continue processing. The following Access Method Services 
commands ar& supported in a TSO environment'* 
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ALTER 
BLDINDEX 
CNVTCAT 
DEFINE - 

ALIAS 

ALTERNATEINDEX 

CLUSTER 

GENERATIONDATAGROUP 

NONVSA.M 

PAGESPACE 

PATH 

SPACE 

USERCATALOG. 
DELETE 
EXPORT 
EXPORTRA 
IMPORT 
IMPORTRA 
LISTCAT 
LISTCRA 
PRINT 
REPRO 
RESETCAT 
VERIFY 

The command you issue is processed immediately. You cannot issue 
modal commands (that is, the IF, THEN, ELSE, DO, END, PARM, and 
SET commands) that modify or make conditional the processing of 
subsequent functional commands. 

The restrictions that apply to the coding of Access Method 
Services commands are described in the "Language Considerations" 
and "Time Sharing Option (TSO)" sections. Other TSO restrictions 
are noted with the descriptions of each appropriate parameter. 



FROM A USER'S PROGRAM 



A processing program can invoke Access Method Services with the 

ATTACH, LINK or LOAD and CALL macros. Before the program issues 

the invoking macro, however, it must initialize the appropriate 

register and argument list contents. 

The register contents follow standard linkage conventions; that 
is, register 1 contains the address of the argument list, 
register 13 contains the address of a save area, register 14 
contains the address of the return point, and register 15 
contains the address of the entry point IDCAMS in Access Method 
Services. 

The contents of the argument list are described in Appendix G. 



AUTHORIZED PROGRAM FACILITY 



The authorized program facility (APF) limits the use of 
sensitive system services and resources to authorized system and 
user programs. See "Authorized Program Facility (APF)" in QS/VS2 
System Programming Library- Supervisor , for information about 
program authorization. 

All Access Method Services load modules are contained in 
SYS1.LINKLIB, and the root segment load module (IDCAMS) is link 
edited with the SETCODE AC(1) attribute. These two 
characteristics ensure that Access Method Services executes with 
APF authorization. 

APF authorization is established at the job step task level. If, 
during the execution of an APF-authori zed job step, a load 
request is satisfied from an unauthorized library, the task will 
be abnormally terminated. It is the installation's 
responsibility to ensure that a load request cannot be satisfied 
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from an unauthorized library during Access Method Services 
processi ng. 

The following situations could cause the APF authorization of 
Access Method Services to be violated: 



An Access Method Services module 
unauthorized library. 



i s loaded from an 



A user security verification routine (USVR) is loaded from 
an unauthorized library during Access Method Services 
processi ng. 

An Exception Exit routine is loaded from an unauthorized 
library during Access Method Services processing. 



A usei — supplied special graphics table is loaded from 
unauthorized library during Access Method Services 
processing. 



an 



Since APF authorization is established at the job step task 
level> Access Method Services will not be authorized if invoked 
by an unauthorized problem program or an unauthorized Terminal 
Monitor Program (TMP). 
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Under TSO, if your sys 
Unit (VS2. 03.813) or t 
Product, you can autho 
the SETCODE AC(1) attr 
Selectable Unit or the 
Product you must enter 
commands requiring APF 
under TSO in the autho 
TSO/VTAM Selectable Un 
TSO for information on 
list. If you have the 

Product, see 0S/VS2 MV 

Reference for the same information. 

The restricted functions performed by Access Method Services 
that cannot be requested in an unauthorized state are J 

REPRO — the copy catalog facility, or the catalog 
unload/reload facility. 

PRINT — when the object to be printed is a VSAM catalog. 

LISTCRA 

EXPORTRA 

RESETCAT 

If the above functions are required and Access Method Services 
is invoked from a problem program or a TSO Terminal Monitor 
Program, the invoking program must be authorized. 



VSAM DATA SETS 



You need to know about the structure and treatment of VSAM data 
sets to use Access Method Services. VSAM data can be stored in 
key sequence, entry sequence, or record-number sequence. 

Records in a key-sequenced data set ar& stored in the order 
defined by the collating sequence of the contents of the key 
field in each record. Each record has a unique value, such as 
employee number or invoice number, in the key field. To 
determine where to insert a new record, VSAM uses an index that 
pairs the key of a record with the record's location. 
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Records in an entry-sequenced data set are stored without 
respect to the contents of the records. Their sequence is 
determined by the order in which they are stored- their entry 
sequence. A new record is stored after the last record in the 
data set . 

Records in a relative-record data set are stored without respect 
to their contents and to their sequence of entry. Their sequence 
is determined by the usei — specified record number that 
identifies the record's position in the data set. Each record is 
fixed-length and is stored in a slot. Records can be inserted 
between other records (that is, i n an empty slot between two 
filled slots), can be added to the end of the data set, or can 
replace records within the data set. 

When a data set is created, it is defined, along with its index, 
if any, in a cluster. A key-sequenced data set and its index 
make up a cluster. An entry-sequenced or relative record data 
set is also defined as a cluster, even though it does not have 
an in.dex. 

Apart from the primary index, one or more alternate indexes can 
be built over a single key-sequenced or entry-sequenced data 
set. Each alternate index accesses the data records of a given 
data set via a different key field (the alternate key) within 
these records. A VSAM cluster that contains data records pointed 
to by an alternate index is called a base cluster. 

In order to gain access to a base cluster via an alternate 
index, you must define a path between the alternate index and 
the base cluster. When a path is defined, you must specify the 
name of the alternate index which is to be considered as the 
entry for the path. The termination of the path is the base 
cluster to which the alternate index is related. The path, which 
is an entry in the catalog, has a name of its own which always 
refers to the alternate index and the related base cluster as a 
pair. 

In addition to data sets, VSAM accesses catalogs. All 

data — -ordinary user data, indexes, and catalogs — is physically 

stored and .manipulated in the same way. 

Refer to Planning for Enhanced VSAM Under QS/VS for more 
information on the structure of VSAM data sets and how data is 
physically stored. 



VSAM VOLUME OWNERSHIP 



VSAM gets and manages space on a storage volume in units called 
data spaces. One or more data sets are stored in a data space. 
Conversely, a data set may be stored in one or more data spaces, 
on one or more storage volumes. Data sets and data spaces may be 
extended beyond their original size. Data spaces are extended by 
whole numbers of tracks or cylinders; VSAM extends them 
automatically as more space is needed. A data space can be as 
large as a volume and can have a maximum of 16 extents. 

VSAM data spaces are defined in a VSAM catalog. That catalog 
controls (owns) the volumes that contain the data spaces defined 
in the catalog, including the volume that contains the catalog 
itself. The catalog also owns candidate volumes for VSAM data 
sets defined in the catalog. VSAM ownership of a volume is 
established with the DEFINE USERCATALOG or DEFINE SPACE commands 
or when the UNIQUE attribute is specified with DEFINE CLUSTER, 
DEFINE ALTERNATEINDEX, or DEFINE PAGESPACE. 

All VSAM clusters, alternate indexes, page spaces, and data 
spaces stored on a volume must be cataloged in the catalog that 
owns the volume. On the other hand, nonVSAM data sets can be 
cataloged in any VSAM catalog. 
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VSAM's ownership and usage of space on a volume is indicated in 
the volume's table of contents (that is, in DSCBs in the 
volume's VTOC). Two data-set security bits in the format-1 
(Identifier) DSCB of each VSAM data space on the volume are set 
to indicate that a password is required to read or write data in 
the data space. (They are set whether the object or objects in 
the data space are actually password-protected or not.) The 
ownership bit in the volume's format-4 (VTOC) DSCB is set to 1. 
The ownership bit indicates that the volume is owned by a VSAM 
catalog, but does not identify the owning catalog. Each VSAM 
catalog contains a volume entry for each volume it owns. The 
volume entry describes the volume's characteristics, each extent 
of the volume's VSAM data space(s), and each VSAM object that 
uses the volume's space. 

In order to take away the ownership of a volume from a VSAM 
catalog, you must first delete all VSAM objects and then all 
data spaces on the volume. The DELETE SPACE command deletes the 
VSAM data spaces on the volume, removes the volume entry from 
the catalog, and revises the format-4 DSCB in the volume's VTOC. 
When you are unable to use the DELETE command because Access 
Method Services can no longer access the volume (due to damage 
that resulted from a system or hardware failure), you can reset 
the ownership bit by using the ALTER REMOVEVOLUMES command (see 
"Modifying Catalog Information"). 

The VTOC contains the name of each VSAM data space on the 
volume, and might contain VSAM-generated names for the data and 
index components of a cluster, alternate index, or page space. 
When you name the data or index component of a VSAM data set, 
alternate index, or page space, and when the object or its 
component is in its own data space (that is, it was defined with 
the UNIQUE attribute), the name of the component identifies the 
data space. Otherwise, VSAM generates a name for the data space. 
The name generated by VSAM has the following format* 

• For a data space containing suballocated VSAM objects, the 
VSAM generated name is* 

2999999n.VSAMDSPC.Taaaaaaa.Tbbbbbbb 

where : 

n=2 if no catalog resides in the data space 

n=4 if a user catalog resides in the data space, or if 
the master catalog resides in the data space and the 
master catalog was created under 0S/VS2 Release 2 or a 
later release 

n=6 if the master catalog resides in the data space 

aaaaaaabbbbbbb is the timestamp value 

• For a unique data space (that is, a data space that cannot 
contain more than one cataloged VSAM object), the 
VSAM-generated name is- 

VSAMDSET . Tbbbbbbb . DFDyyddd . Taaaaaaa . Tbbbbbbb 

where : 

yyddd is the date (year and Julian day) 

aaaaaaabbbbbbb is the timestamp value 

When you define a VSAM data set with the UNIQUE attribute, VSAM 
creates a unique data space. If you specify a name for the data 
and/or index component, VSAM places the name you specify in the 
format-1 DSCB rather than generating a name. 

When you delete a VSAM data set with the UNIQUE attribute, the 
data space is also deleted (the volume must be mounted). The 
volume ownership bit is turned off; the volume entry in the 
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I catalog is turned off. 



If you do not specify a name for the data and index components 
of a suballocated VSAM data set (that is, a data set which 
shares a data space with other VSAM data sets), VSAM generates a 
name for these components. The format of the VSAM-generated name 
is the same as that shown above for a unique data space. 

To relate the VSAM-generated name with a VSAM cluster, alternate 
index, page space, catalog, or data space, you list the catalog 
that owns the volume. You issue a LISTCAT command to list the 
catalog's contents. The LISTCAT output listing relates the 
VSAM-generated names with usei — assigned entrynames for cataloged 
objects. 

Each volume owned by a VSAM catalog contains two timestamps that 
are written in the format-^ DSCB when the volume is first 
cataloged. Both timestamps are updated but only one (the second) 
is checked. The first timestamp is maintained for compatibility 
with earlier VSAM releases. The volume timestamps are updated as 
follows: 



• For a volume owned by a recoverable VSAM catalog, each time 
the catalog's volume record is modified. 

• For a volume owned by a nonrecoverable VSAM catalog, each 
time space is allocated, extended, or scratched by VSAM. 
When the volume is mounted, the system compares the second 
timestamp on the volume to the timestamp in the volume 
record in the catalog owning the volume. If the volume's 
timestamp is earlier than the catalog's timestamp, the 
volume is considered downlevel. Access Method Services will 
not normally open a data set on a down-level volume. 

Some of the implications of VSAM volume ownership are: 

• All VSAM clusters, alternate indexes, page spaces, and data 
spaces on a volume must be cataloged in the catalog that 
owns the volume. Only one VSAM catalog can own the volume. 

• VSAM volume ownership does not affect nonVSAM data sets that 
reside on the volume. NonVSAM data sets can exist on a 
volume owned by a VSAM catalog, and can ( but should not ) be 
cataloged in a catalog that does not own the volume. Since 
OS control volumes (CVOLs) are considered nonVSAM data sets, 
an OS CVOL can also exist on a volume owned by a VSAM 
catalog. 



In order to release a volume from 
catalog, you must delete all VSAM 
volume. The catalog also contains 
describes the volume and its VSAM 
deleting the VSAM objects, you is 
command. The DELETE SPACE command 
spaces on the volume, removes the 
catalog, and revises the format-1 
volume's VTOC. You can delete all 
volume whether or not they contai 
specifying the FORCE option on th 



ownership by a VSAM 
objects that reside on the 
a volume entry which 
data spaces. After 
sue the DELETE SPACE 
deletes the VSAM data 
volume entry from the 
and format-4 DSCBs in the 
VSAM data spaces on a 
n VSAM objects by 
e DELETE SPACE command. 



A user catalog cannot exist on a volume that contains active 
page spaces, paging data sets (that is, system data sets 
that are paged into and out of the CPU's virtual storage), 
or the SYS1 .STGINDEX. These objects are cataloged in the 
master catalog and, therefore, the volume(s) on which they 
reside are owned by the master catalog. 
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VSAM'S USE OF CATALOGS 



Most uses of Access Method Services involve doing something to 
the VSAM catalogs. For example, establishing a VSAM data set 
involves creating an entry in a catalog; deleting a VSAM data 
set involves removing an entry from the catalog; and moving a 
VSAM data set from one system to another involves moving an 
entry from a VSAM catalog in one system to a VSAM catalog in 
another system. The use of Access Method Services with VSAM 
requires an understanding of how VSAM uses catalogs. 

VSAM uses catalogs as a central information point for all VSAM 
data sets and the direct-access storage volumes on which they 
are stored. There are two kinds of VSAM catalogs: master 
catalogs and user catalogs. In addition, OS CVOLs (control 
volumes) can be attached to a VSAM master catalog. In an 0S/VS2 
system, the VSAM master catalog is the system's primary catalog 
and is required. Any number of VSAM user catalogs are optional. 
The system's nucleus contains a pointer to the VSAM master 
catalog, which in turn points with catalog connector entries to 
any VSAM user catalogs. The OS CVOLs are cataloged in the master 
catalog as nonVSAM data sets with the name "SYSCATLG. catname. " 

Catalogs provide VSAM with the information to allocate space for 
data sets, verify authorization to gain access to them, compile 
usage statistics on them, and relate RBAs to physical locations. 

For a VSAM data set to exist, it must be defined in a VSAM 
catalog. That is, you must enter in the catalog a data set's 
name and other facts about it by using Access Method Services to 
define it. 

All VSAM data sets on a volume must be cataloged in the same 
catalog, either the master catalog or a user catalog. A data set 
is defined in only one catalog. VSAM "ownership" of a volume by 
a catalog is established the first time VSAM space is allocated 
on that volume. The DEFINE with the UNIQUE attribute (of a 
cluster, alternate index, or page space), DEFINE USERCATALOG, or 
DEFINE SPACE commands establish such ownership. All subsequent 
VSAM data sets defined on the volume are required to be defined 
in the same catalog (that is, the catalog that owns the volume). 

When you execute a program to process a data set, catalogs are 
searched to find out which volume(s) the data set is stored on, 
unless you give volume serial number(s) by way of JCL. 

The order in which catalogs are searched depends on whether 
catalogs are specified for the current job step (STEPCAT) or job 
(JOBCAT), whether the name of the data set is a qualified 
entryname, and on whether the catalog is to be used to define a 
new entry or searched for existing entries. See "Order of 
Catalog Use" for an explanation of how a catalog is selected 
during the processing of an Access Method Services command. 
("Order of Catalog Use" sections appear in the chapters that 
describe each of the following commands: DEFINE, BLDINDEX, 
ALTER, LISTCAT, and DELETE.) 

Note ; An unqualified name and a qualified name cannot exist in 

the same catalog if the first qualifier of the qualified name is 

the same as the unqualified name. For example, DATA and 
DATA. PAYROLL cannot exist in the same catalog. 

Figure 2 illustrates how data sets in an 0S/VS2 system can be 
divided up for cataloging among the VSAM master catalog, VSAM 
user catalogs, and OS control volume catalogs (CVOLs). 
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Figure 2. Catalog Relationships in an 0S/VS2 System 



If you need information on the structure of a VSAM catalog or 
more details on the information contained in the catalog, refer 
to Planning for Enhanced VSAM Under QS/VS . 



THE MASTER CATALOG 



In an 0S/VS2 system, the VSAM master catalog is the system's 
primary catalog. When you generate the system (that is, when you 
use the SYSGEN procedure), you define the system's master 
catalog during the first step in Stage II of SYSGEN. The name 
you specify for the catalog must be different from the name of 
the master catalog of the driving system. See 0S/VS2 System 
Programming Librarv ; System Generation Reference for details on 
the system generation process. 

The master catalog does not have to reside on the IPL volume. 
The SYSCATLG member of SYS1 .NUCLEUS, a nonVSAM data set on the 
IPL volume, points to the volume containing the master catalog. 
The SYSCATLG member is referenced during IPL and NIP processimg. 
It is recommended that the master catalog and VSAM objects 
cataloged in it not reside on the IPL volume — if the master 
cacalog has to be recovered, then restoring the master catalog 
will not affect the IPL volume. 

The master catalog is the only catalog referenced during NIP 
processing. Therefore, all system data sets, data sets entered 
in LNKLSTxx, paging data sets, and libraries specified in the 
JES start procedure must be cataloged in the master catalog, and 
not in a user catalog or an OS control volume (CVOL). 
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You cannot move the master catalog from one system to another by 
using the EXPORT and IMPORT commands. You can, however, use the 
REPRO command to make a copy of the master catalog, then move 
the copy to another system. If your master catalog is 
recoverable, you can use the LISTCRA, EXPORTRA, IMPORTRA, and 
RESETCAT commands to repair damaged entries that result from 
system failure. "Appendix H: Changing the Attributes of the VSAM 
Master Catalog" describes how you can create a new master 
catalog for your system. This procedure assumes that you already 
have a valid master catalog with which to IPL your system. If 
your master catalog has somehow been destroyed, you can create a 
new one on another system using the appropriate portion of the 
same procedure described in Appendix H. 

A master catalog cannot be used simultaneously as the VSAM 
master catalog for two 0S/VS2 systems (that is, the master 
catalog cannot be shared between two systems as each system's 
master catalog). However, one system's master catalog can be 
used as a user catalog on another 0S/VS2 system that includes 
VSAM when the catalog i s on a shared direct-access device. When 
a catalog is used simultaneously by two or more systems, all of 
the catalog's volumes must be on shared direct-access devices. 
If you do this, take care to assign passwords to each of the 
catalog's page spaces and system data sets to prevent their 
accidental or unauthorized use. 



TRANSPORTING USER CATALOGS 



You can move a user catalog to another system that includes VSAM 
(that is, to an 0S/VS1 or 0S/VS2 system or to a DOS/VS system) 
to make the objects cataloged in the user catalog available to 
the other system. The user catalog might own only the volume on 
which it resides. In this case, the volume can be moved as a 
single unit to another system. When the catalog owns more than 
one volume, either all volumes owned by the catalog must be 
moved to the other system or the catalog's ownership of the 
volumes that are not moved must be taken away before the catalog 
i s moved. 

You can use the EXPORT command with the DISCONNECT parameter to 
remove a user catalog from its OS/VS system. The EXPORT command 
deletes the user catalog's connector entry in the master 
catalog. The catalog, its cataloged objects, and its volume(s) 
become unavailable to the old system. 

You use the IMPORT command with the CONNECT option to make the 
exported catalog available to the new 0S/VS1, 0S/VS2, or DOS/VS 
system. The IMPORT command builds a connector entry in the 
master catalog that identifies the user catalog's volume. If you 
want the connector entry built to another user catalog's volume, 
the CATALOG parameter must be specified and must agree with the 
STEPCAT or JOBCAT DD statement. 



JOBCAT AND STEPCAT DD STATEMENTS 



User catalogs can be dynamically allocated. User catalogs can 
also be allocated directly, by using a JOBCAT or STEPCAT DD 
statement. A previous section, "JCL and Dynamic Allocation," 
discusses dynamic allocation of catalogs and cataloged objects. 

You can specify a catalog that is to be available for use only 
with a job step, or that is to be available for the entire job. 
A STEPCAT DD statement identifies a catalog that is available 
for a single job step; a JOBCAT DD statement identifies a 
catalog that is available during the entire job. When both 
JOBCAT and STEPCAT catalogs are specified, the user catalog 
specified by STEPCAT is used for the job step. The JOBCAT and 
STEPCAT statements you code should be in the form: 

//JOBCAT DD DISP={OLD|SHR}, 
// DSNAME = usercatname 
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and 

//STEPCAT DD DISP= (OLD| SHR} , 
// DSNAME=usercatname 

Because the master catalog contains information about each user 
catalog, you do not need to specify the catalog's volume and 
device information. 

You can specify more than one user catalog for a job or job 
step. To indicate another user catalog, follow the JOBCAT or 
STEPCAT DD statement with a concatenated DD statement — an 
unlabeled DD statement that specifies the name of another user 
catalog: 

//STEPCAT DD DISP=SHR,DSN=MGMTCAT1 
// DD DISP=SHR,DSN=MGMTCAT2 

You can supply a JOBCAT or STEPCAT DD statement to allocate the 
catalog when : . 

• Your job processes a user catalog (that is, when your 
sequence of Access Method Services commands adds, modifies, 
lists, or deletes a VSAM catalog entry) 

• Your job includes a space allocation request directed toward 
a volume that contains VSAM data spaces (that is, a DEFINE 
SPACE or DELETE SPACE command) 

• Your job causes a VSAM data set to be opened and that data 
set i s defined in a user catalog (that is, a REPRO or PRINT 
of a VSAM data set, a DELETE with the ERASE option, EXPORT, 
IMPORT, IMPORTRA, BLDINDEX, or VERIFY) 

Refer to "Copy-Catalog Procedure" for information on REPRO 
and JOBCAT/STEPCAT DD statements. 

The description of each of the commands that adds, modifies, 
lists, or deletes VSAM catalog entries contains a section, 
"Order of Catalog Use," which explains how VSAM selects a 
catalog for use by a particular job. 

You must supply either a JOBCAT or STEPCAT DD statement to 
allocate the catalog when: 

• Your job uses IEHDASDR to dump a volume owned by a user 
catalog 

• Your job causes the catalog to be opened as a data set (for 
example, using the PRINT command to print a catalog, using 
the LISTCRA command with the COMPARE option, using the 
VERIFY command to restore end-of-file indicators of a user 
catalog) 

• Your job causes the scheduler allocation of the user catalog 
to be bypassed because unit and volume information were 
specified on the DD statement describing the VSAM data set 
defined i n that user catalog 

You can minimize the use of JOBCAT and STEPCAT DD statements for 
your jobs when you name your data set with a qualified entryname 
whose first qualifier is the name or alias of the catalog in 
which the data set is defined. When the catalog is not 
identified with a JOBCAT or STEPCAT DD statement or explicitly 
named (that is, with an Access Method Services command's CATALOG 
parameter), the OS/VS scheduler searches the master catalog for 
the data set's entryname. If the entryname is not found, the 
system uses the entryname 1 s first qualifier as a search argument 
and attempts to locate either a usei — catalog connector entry or 
a user catalog's alias entry. If the system finds a use» — catalog 
connector entry (that is, an entry whose name or alias is the 
same as the entryname' s first qualifier), the system searches 
that user catalog for the data set's entry, using the data set's 
full entryname. 
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OS CONTROL VOLUMES (CVOLS) 



In addition to the VSAM master catalog, your system can include 
user (or private VSAM) catalogs and OS control volumes (CVOLs or 
private OS catalogs). The system's catalog structure can be 
organized with a master catalog only, or with a master catalog 
and any combination of one or more user catalogs and/or OS 
CVOLs. 

The master catalog (the primary level) points \o each user 
catalog and OS CVOL in the system. A VSAM user catalog cannot be 
accessed via another user catalog or OS CVOL. 

The VSAM master catalog provides the following benefits in your 
0S/VS2 system-* 

• Portability of catalogs between systems 

• The capability of mounting, as needed, the volumes 
containing catalogs 

• Minimization of the effect of errors or damaged entries on a 
catalog 

• Performance improvements by reducing contention for a 
catalog 

The following differences between VSAM user catalogs and OS 
CVOLs might affect your choice of having user catalogs or OS 
CVOLs on your system* 

• You cannot catalog VSAM objects in an OS CVOL. 

• You cannot use Access Method Services commands to catalog 
objects in, or modify existing entries of, an OS CVOL. 

• You can convert an OS CVOL's entries to VSAM catalog entries 
when you use the CNVTCAT command, but there is no- 
corresponding facility to convert VSAM catalog entries to OS 
CVOL entries. 

• A user catalog requires at least twice as much space as a 
corresponding OS CVOL. 

• User catalogs can be moved only to other OS/VS systems that 
include VSAM. OS CVOLs can be moved to MVT and 0S/VS2 
systems that might not include VSAM. 

You can use the DEFINE NONVSAM command to define a CVOL (as 
though it were a nonVSAM data set) in the master catalog when 
you name it ' SYSCATLG. qual i f i er» . You can't use IEHPROGM to 
create or extend a CVOL. 

Many users choose to use OS CVOLs initially, then convert the 
CVOLs to user catalogs when their system is running smoothly. 
Whether you use an OS CVOL or a user catalog, nonVSAM data sets 
are cataloged and uncataloged by your specification of the DD 
statement's DISP parameter (see 0S/VS2 JCL for more details on 
DD statements and job control language). VSAM objects are 
cataloged and uncataloged in VSAM catalogs by using Access 
Method Services commands. 
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TIME SHARING OPTION (TSO) 



TSO is a subsystem of 0S/VS2 that provides conversational time 
sharing from remote terminals. You can use TSO with VSAM and 
Access Method Services to: 

• Execute Access Method Services commands 

• Execute a program to call Access Method Services 

When TSO i s used with Access Method Services, the following 
differences must be observed- 

• TSO allows the initial characters of a keyword to be 
supplied as an abbreviation of the keyword. The only 
restriction is that enough initial characters must be 
supplied to make the keyword unique. TRACKS* for example, 
could be abbreviated TR, TRA, or TRAC, because no other 
keyword within the same command can be abbreviated in the 
same way. 

Some abbreviations which are acceptable to Access Method 
Services such as CYL, CYLINDER, REC, RECORD cannot be used 
under TSO because the abbreviations do not contain enough 
initial characters to make the keyword unique. TSO can't 
tell whether you mean CYLINDERS or CYLINDERFAULT when CYL or 
CYLINDER is used. Similarly, abbreviations REC and RECORD 
are ambiguous; TSO doesn't know if you mean RECORDS or 
RECORDSIZE. 

• In addition, the abbreviations described in the remainder of 
this publication (for example, TRK for TRACKS) are 
acceptable to TSO. 

• When a parameter's value consists of a list of one or more 
parenthesized parameter sets, the outer parentheses 
surrounding the list are always required. For example, if 
lowkey and highkey form a parameter set that can be repeated 
several times, then the outer parentheses are required even 
when just one parameter set i s specified; as follows* 

KEYWORDU lowkey highkey)) 

• A name can be specified in quotation marks or not in 
quotation marks. Under TSO, however, a prefix (for example, 
the userid) is added to a name that is not in quotation 
marks. The prefix becomes the first qualifier in the name. 
If the name is a volume serial number (as it may be in the 
DELETE command, for example), enclose it in quotation marks; 
if you do not, a prefix is added to the volume serial 
number. 

• Under TSO, a volume serial number can consist of alphabetic, 
national, numeric, or special (hyphen only) characters; if 
any other characters &re used, the volume serial number 
cannot be used as an entryname under TSO. 

• Under TSO, a password can be supplied with any entryname; 
the password is ignored if not required. 

Note: At a TSO terminal, the logon password is checked first 
before the user is prompted to supply a password for a 
cluster. Checking the logon password counts as one attempt 
to obtain a password. If the user has not specified ATTEMPTS 
in his DEFINE command, he has one attempt to supply the 
catalog's password because the default is two. 

• The modal commands, used to control execution ( IF-THEN-ELSE 
command sequence, DO-END command sequence, SET, and PARM), 
are not allowed under TSO. 
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• Under TSO, the user is prompted to complete a 
fully-qualified name. The user is also prompted to supply 
required, but omitted, parameters. 

• Under TSO, the SYSPRINT data set is not used. The OUTFILE 
parameter may be used to specify a data set to receive the 
output procedure from Access Method Services commands. 

For details about the format of a displayed catalog entry 
(resulting from a LISTCAT command) for a TSO user, see "Appendix 
B. Interpreting LISTCAT Output Listings." 

For details about writing and executing programs and allocating 
data sets with TSO, see 0S/VS2 TSO Terminal User's Guide and 
QS/VS2 TSO Command Language Reference . 



MASS STORAGE SYSTEM (MSS) 



The IBM 3850 Mass Storage System can be used with 0S/VS2 to 
store a massive amount of data online to the operating system. 
It is described in the Introduction to the IBM 3850 Mass Storage 
System (MSS) . 

When you have the Mass Storage System, you can define VSAM data 
spaces, user catalogs, and data sets and nonVSAM data sets on 
mass-storage volumes. The master catalog cannot be stored on a 
mass-storage volume. 

A VSAM catalog may have defined in it both objects stored on 
direct-access storage volumes and objects stored on mass-storage 
volumes. In particular, the data component of a key-sequenced 
cluster may be stored on a mass-storage volume and the index 
component on a direct-access storage volume, or vice versa. 

Space for an object larger than one cylinder that is stored on a 
mass-storage volume should be allocated in cylinders to optimize 
data transfer (staging and destaging) between mass-storage and 
direct-access storage. 

Data stored in the Mass Storage System is staged from mass 
storage to a direct-access storage staging drive when the object 
to which the data belongs is opened or when the data is 
requested. It is destaged from the staging drive to mass-storage 
when the object is closed. (The Introduction to the IBM 3850 
Mass Storage System (MSS) tells what direct-access storage 
devices can be used for staging.) 

Access Method Services for the Mass Storage System provides a 
set of commands for the management of mass-storage volumes. 
These commands are described in QS/VS Mass Storage System (MSS) 
Services: Reference Information . 

Access Method Services for managing VSAM catalogs provides 
parameters for options of the Mass Storage System in the DEFINE 
and ALTER commands, which enable you to specify how a VSAM data 
set that is stored on a mass-storage volume is to be staged and 
destaged and how a user catalog that i s stored on a mass-storage 
volume is to be destaged. These parameters are described in this 
book. 

The staging attributes, BIND, CYLINDERFAULT, and STAGE, affect 
performance. BIND causes an object to be staged when it is 
opened and to be retained (bound) in direct-access storage. 
CYLINDERFAULT causes portions of an object to be staged only as 
needed during processing. STAGE i s a compromise: the object is 
staged when it is opened, but not retained in direct-access 
storage. When the staging activity of other objects is light, 
STAGE can achieve results similar to BIND: the data might remain 
in direct-access storage, available for requests for access 
without staging. When the staging activity of other objects is 
heavy, STAGE can achieve results similar to CYLINDERFAULT: the 
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data might not remain in direct-access storage and might have to 
be restaged when needed. 

A user catalog that is stored on a mass-storage volume is always 
staged and bound when it is opened — that is, it is retained in 
direct-access storage until it is closed. Not binding a user 
catalog might degrade performance. 

A CRA is opened when it is first needed, and will remain open 
for as long as the user catalog is open. Because of this, the 
CRA volume must remain mounted during that period of time. 

The destaging attributes, DESTAGEWAIT and NODESTAGEWAIT, affect 
data integrity. DESTAGEWAIT causes VSAM to return control to the 
program that closes an object synchronously — only after 
destaging is complete. VSAM can notify the program whether 
destaging was successful. NODESTAGEWAIT causes VSAM to return 
control to the program asynchronously — as soon as the object is 
closed, but before it has been destaged. 

A failure in destaging causes a message to be written to the 
operator. With DESTAGEWAIT, an error code is also returned from 
CLOSE to the processing program. But there &rQ no recovery 
procedures for a program to undertake? one use of DESTAGEWAIT is 
for a processing program to periodically issue a temporary CLOSE 
of a bound object to cause it to be destaged at various 
checkpoints. The processing program can terminate processing if 
a failure occurs in destaging. The last copy destaged would be 
the copy to fall back to, pending correction of the error that 
caused the failure. 

A data component that is defined with the ERASE parameter and 
stored on a mass-storage volume, is overwritten with binary 
zeros on the staging drive after it is destaged. 

Note: On MSS volumes, a GDG data set may not be scratched when 
it is automatically uncataloged, even if the SCRATCH option was 
specified in the DEFINE. 
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DATA SECURITY AND PROTECTION 



The protection of data includes data security* or the safety of 
data from theft or intentional destruction, and data integrity, 
or the safety of data from accidental loss or destruction. 
Security and integrity options are specified by an entry in the 
DEFINE command. 



DATA-SET SECURITY 



Access Method Services provides options to protect data sets 
against unauthorized use and loss of data. To effectively use 
the protection features, you must understand the difference 
between two different operations: 1) referring to a catalog 
entry and 2) using the data set represented by a catalog entry. 
A catalog entry is referred to when new entries are defined 
(DEFINE), or old entries are altered (ALTER), deleted (DELETE), 
or listed (LISTCAT). The data set represented by the catalog 
entry is used when it is connected to a user's program (OPEN), 
or disconnected (CLOSE), or when it reaches its upper 
RBA-boundary ( End-of-Volume) . The distinction between these two 
operations is the key to understanding how the VSAM passwords 
work; different passwords may be needed for the two operations. 

The data-set security options are described in the sections that 
follow. 



PASSWORDS TO AUTHORIZE ACCESS 



You can optionally define passwords for clusters, cluster 
components (data and index), page spaces, alternate indexes, 
alternate index components (data and index), paths, and VSAM 
catalogs, which a person must give to get permission to gain 
access to them. There are different passwords for various 
degrees of security. The higher levels provide greater 
protection than the lower levels. The levels are: 

• Full access . This is the master password, which allows you 
to perform all operations (retrieving, updating, inserting, 
and deleting) on a data set and any index and catalog record 
associated with it. Using this password to gain access 
allows you to delete an entire VSAM data set and to alter 
any catalog information (including passwords) about the data 
set, index, or catalog, except the cataloged object's 
physical-extent descriptors. The master password allows all 
operations and bypasses any additional verification checking 
by the usei — security-verification routine. 

• Control access . This password authorizes you to use 
control-interval access. See OS/VS Virtual Storage Access 
Method (VSAM) Options for Advanced Applications for 
information on the use of control-interval access. 

• Update access . This password authorizes you to retrieve, 
update, insert, or delete records in a data set . Speci fyi ng 
a catalog's update password authorizes you to define data 
sets in it, and to alter or delete nonVSAM and GDG entries 
in it. 

• Read access . This is the read-only password, which allows 
you to examine data records and catalog records, but not to 
add, alter, or delete them, nor to see password information 
in a catalog record. 



Data Security and Protection 



If you define passwords for any data sets in a catalog* you must 
also define passwords for the catalog in order for the data-set 
passwords to have effect. If you do not define passwords for the 
catalog* no password checking will take place during operations 
on the data set's catalog entries. 

Operations on a catalog may be authorized by the catalog's 
appropriate password or, in some cases* by the appropriate 
password of the data set whose definition in the catalog is 
being operated on. For example* defining a data set in a 
password-protected catalog requires the catalog's update (or 
higher) password. Listing or deleting a definition requires the 
appropriate password of either the catalog or the data set. . 
However* if the catalog* but not the data set* is protected, you 
need give no password to list the data set's catalog definition. 

Because a user catalog defines itself, it may be 
password-protected without the mastei — catalog being 
password-protected. To delete a user catalog, you must give its 
master password* whether the master catalog i s 
password-protected or not. 

Each highei — level password allows all operations permitted by 
lower levels. Any level may be null (not specified)* but if a 
low-level password is specified* the mastei — level password must 
also exist. The DEFINE and ALTER commands accomplish this by 
giving all of the higher passwords the value of the highest 
password specified. Thus* if you specify only a read-level 
password, that password will become the update-* control-* and 
mastei — level password as well. If you specify a read password 
and a control password* the control-password value will become 
the mastei — level password as well. However* the update-level 
password will be null. 

One reason for password-protecting the components of a cluster 
is to prevent access to the index of a key-sequenced data set* 
since the only way to gain access to an index is to open it 
independently of the cluster. (See OS/VS Virtual Storage Access 
Method (VSAM) Options for Advanced Applications for a 
description of access to an index.) 

Some Access Method Services operations may involve more than one 
password authorisation. For example* importing a data set 
involves defining the data set and loading records into it. If 
the catalog into which the data set is being imported is 
password-protected* its update- (or higher-level) password is 
required for the definition; if the data set is 
password-protected* its update- (or highei — level) password is 
required for the load. The IMPORT and IMPORTRA commands allow 
you to specify the password of the catalog; the password, if 
any* of the data set being imported is obtained by the commands 
from the exported data. 

Every VSAM data set is represented in the VSAM catalog by two or 
more entries 1 a cluster entry and a data entry* or* if the data 
set is a key-sequenced data set, a cluster entry* a data entry, 
and an index entry. Of the two or three entries* the cluster 
entry is the controlling entry. Each of the two or three entries 
can have its own set of four passwords* the passwords you assign 
have no relationship to each other. For example* if you 
password-protect a cluster but don't password-protect the 
cluster's data component, someone could issue LISTCAT to 
determine the name of your cluster's data component* then open 
the data component and access records in it — even though the 
cluster itself is password protected. 

Catalogs are themselves VSAM data sets* and may have passwords. 
For some operations (for example* listing all of a catalog's 
entries with their passwords or deleting catalog entries)* the 
catalog's passwords may be used instead of the entry's 
passwords. Thus, if the master catalog is protected* the update- 
or highei — level password is required when defining a user 
catalog. This is because all user catalogs have an entry in the 
master catalog. When deleting a protected user catalog* the user 
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catalog's master password must be specified. 

The following protection considerations and precautions should 
be observed when using commands which refer to the VSAM catalog: 

• Passwords are 1 to 8 EBCDIC characters, either alphameric or 
special characters, and may use hexadecimal format (see the 
CONTROLPW, MASTERPW, READPW, and WRITEPW definitions in the 
"Command Format" chapter). 

• To create a catalog entry (with the DEFINE command), the 
update- or highei — level password of the catalog is required. 

• To modify a catalog entry (with the ALTER command), the 
master password of the entry or the master password of the 
catalog which contains the entry is required. However, if 
the entry to be modified is a nonVSAM or GD6 entry, the 
update-level password of the catalog is sufficient. 

• To gain access to passwords in a catalog (for example, to 
list or change passwords), you must specify the mastei — level 
password of either the entry or the catalog. Similarly, a 
master-level password must be specified with the DEFINE 
command if you want to model an entry's passwords. 

• To delete a protected data-set entry from a VSAM catalog 
requires the master-level password of the entry or the 
mastei — level password of the catalog containing the entry. 
However, if the entry describes a VSAM data space, the 
update-level password of the catalog is sufficient. If the 
entry to be deleted is a nonVSAM, GDG, or alias entry, the 
update level password of the catalog is sufficient. 

• If the password of the catalog is the read-level, catalog 
entries with the read-level passwords may be listed by 
specifying the read password of the entry or the catalog's 
read level password. However, entries without passwords may 
be listed without specifying the catalog's read-level 
password. If you wish to list the passwords associated with 
a catalog entry, you must specify the master password of the 
entry or the catalog's master password. 

• If the proper password is not specified with the Access 
Method Services command, a password prompt will occur. 
Unless you have specified the CODE parameter on either the 
DEFINE or ALTER command, the prompt will include the name of 
the data set; if you have specified CODE, the prompt will 
include the code name you specified. In some circumstances, 
due to the manner in which catalog entries are referenced, 
more than one prompt may occur. For example, when an ALTER 
or DELETE request is processed, the catalog must be referred 
to twice, once to locate the information, and once to 
perform the requested function. Again, incorrect password 
specification when listing catalog entries may cause 
numerous prompts. To avoid unnecessary prompts, specify the 
catalog's password, which allows access to all entries that 
the operation affects. A catalog's mastei — level password 
will allow you to refer to all catalog entries. However, a 
protected cluster cannot be processed with the catalog's 
master password. 

• Specification of a password where none is required is always 
i gnored. 

The following protection considerations and precautions should 
be observed when using commands which cause a data set access- 

• Passwords are 1 to 8 EBCDIC characters, either alphameric or 
special characters, and may use hexadecimal format (see the 
CONTROLPW, MASTERPW, READPW, and WRITEPW definitions in the 
"Command Format" chapter). 



Data Security and Protection 29 



To access a VSAM data set using its cluster name, instead of 
data or index names, you must specify the proper level 
password for the cluster. The proper level password for the 
cluster is required even if the data or index passwords are 
null. 

To access a VSAM data set using its data or index name, 
instead of its cluster name, you must specify the proper 
data or index password. However, if cluster passwords are 
defined, the master password of the cluster may be specified 
instead of the proper data or index password. 

If a cluster has only null (not specified) passwords, you 
can access the data set using the cluster name without 
specifying passwords. This is true even if the data and 
index entries of the cluster have passwords defined. This 
allows unrestricted access to the VSAM data set as a whole 
but protects against unauthorized modification of the data 
or index as separate components. 



Operator Prompting Code 



Computer operators and TSO-terminal users may be given the 
opportunity to supply a correct password if a processing program 
does not give the correct one when it tries to open a 
password-protected data set. When the data set is defined, you 
may specify a code to be used in lieu of the data-set name to 
prompt the operator or terminal user for a password. The 
prompting code keeps your data secure by not allowing the 
operator or terminal user to know both the name of the data set 
and its password. 

A data set's code is used for prompting for any operation 
against a password-protected data set. The catalog code is used 
for prompting when the catalog is opened as a data set, when an 
attempt is made to locate catalog entries that describe the 
catalog, and when an entry i s to be defined in the catalog. 

If you don't specify a prompting code, VSAM identifies the job 
for which a password i s needed with the JOBNAME and DSNAME for 
background jobs or with the DSNAME alone for foreground (TSO) 
jobs. 



Attempts to Supply a Password 



When you define a data set, you can specify the number of times 
the computer operator or terminal user is allowed to try to give 
the correct password when a processing program is trying to open 
a data set. If the allowed number of attempts is exceeded and 
you are using the System Management Facilities, a record is 
written to the SMF data set to indicate a security violation. 

Note: Using the TSO logon password counts as one attempt. 



PASSWORDS FOR NONVSAM DATA SETS 



When you define a nonVSAM data set in a VSAM catalog, the data 
set is not protected with passwords in its catalog entry. You 
can password-protect a nonVSAM data set when you create it, by 
specifying LABEL=(PASSWORD| NOPWREAD) in the DD statement that 
describes the data set (for more details, see 0S/VS2 JCL ) . You 
use the PROTECT macro instruction to assign a password to the 
nonVSAM data set (for more details, see 0S/VS2 Data Management 
Services Guide and 0S/VS2 System Programming Library: Data 
Management) . 

If the catalog is update protected, you must supply the 
catalog's update- (or highei — level) password in order to define, 
delete or alter a nonVSAM data set. The password can be supplied 
as a subparameter of the command's CATALOG parameter, or as a 
response to the password-prompting message. 
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USER-SECURITY-VERIFICATION ROUTINE 

In addition to password protecti on, VSAM allows you to protect 
data by specifying a program to verify a user's authorization. 
Specific requirements of the usei — security-verification routine 
are described in the chapter "User-Written Exit Routines" in 
QS/VS Virtual Storage Access Method (VSAM) Programmer's Guide . 
To use this routine, simply specify the name of the 
authorization routine you have written in the AUTHORIZATION 
parameter of the DEFINE or ALTER command. 

If a password exists for the type of operation being performed, 
the password must be given, either in the command or in response 
to prompting. The usei — security-verification routine is called 
only after the password specified is verified. The 
user-security-verification routine is bypassed whenever a 
correct master password is specified, whether or not the master 
password is required for the requested operation. 

RESOURCE ACCESS CONTROL FACILITY (RACF) PROTECTION 

Resource Access Control Facility (RACF) provide* an optional 
software access control measure you can use in addition to or 
instead of passwords. Password protection and RACF protection 
can coexist for the same data set. When RACF protection is 
applied to a data set which is already password protected, 
password protection is bypassed and access is controlled solely 
through the RACF authorization mechanism. If a 

Usei — Security-Verification Routine (USVR) exists, it will not be 
invoked for RACF-defined data sets. 

Although passwords are ignored for a RACF indicated data set, 
they can still provide protection if the data set is moved to 
another system which does not have RACF protection. 
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One difference between password authorization checking and RACF 
authorization checking is that deletion of any type of RACF- 
protected entry from a RACF-protected VSAM catalog requires 
alter level authorization either to the catalog or to the entry 
being deleted. 

In order for RACF protection to be applied to a data set, the 
containing catalog must also be RACF protected. In order for 
password protection to be applied to a data set, the containing 
catalog must be either RACF protected or password protected . and 
the data set itself not defined to RACF. 



Refer to 0S/VS2 MVS Resource Access Control Facility (RACF) 
General Information Manual for more information. 
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PROTECTING USER'S DATA 



Sometimes, because of system or hardware failure, your data may 
be destroyed or made inaccessible to you. You should recognise 
the possibility of this occurring and take actions that will 
allow you to recover your data if such a catastrophe happens. 



PREFORMATTING CONTROL AREAS 



When you define a cluster, you can indicate that VSAM is to 
Preformat each control street as records are loaded into the 
cluster (RECOVERY) or i s not to preformat them, in the interest 
of performance (SPEED). Preformatting clears all previous 
information from the direct-access storage area and writes an 
end-of-file indicator* 

• For an entry-sequenced or relative record data set, in every 
control interval in the control area. 

• For a key-sequenced data set, in the first control interval 
in the control area following the Preformatted control area. 
(The Preformatted control area contains free control 
intervals.) 

As records are loaded into a Preformatted control area, there is 
always a following end-of-file indicator that indicates how far 
loading has progressed. If an error occurs that prevents loading 
from continuing, you can readily identify the last successfully 
loaded record and resume loading at that point. 

Without Preformatting, an end-of-file indicator is written only 
after the last record is loaded. If an error occurs that 
prevents loading from continuing, you might not be able to 
identify the last successfully-loaded record — you might have to 
reload the records from the beginning. 



BACKING UP DATA 



Two Access Method Services commands enable you to create a 
backup copy of your data* 

• EXPORT copies a VSAM cluster or alternate index and its 
catalog entries. The copy can be imported to another 0S/VS1, 
0S/VS2, or DOS/VS system that includes VSAM or can be used 
as a backup. 

• REPRO copies a VSAM cluster or alternate index (without its 
catalog entry), a VSAM catalog, or a sequential data set. 
The copy can be used as a backup. 

The choice of using EXPORT or REPRO as a backup depends on a 
number of factors* 

• A backup copy created by EXPORT can only be a sequential 
data set. A backup copy created by REPRO can be a VSAM data 
set or a sequential data set. Also, the backup copy obtained 
by using REPRO can be a different type of VSAM data set than 
the original. You could, for example, back up a VSAM 
key-sequenced data set by copying it to a VSAM 
entry-sequenced data set using REPRO. By using the REUSE 
attribute when using REPRO to back up a VSAM data set, you 
have the facility of taking repeated^ backups to the same 
VSAM reusable target data set. 

• A backup copy created by EXPORT contains all the information 
necessary to redefine the VSAM cluster or alternate index 
when you IMPORT the copy. A backup copy created by REPRO 
does not contain this catalog information. If it is 
necessary to use the backup copy, you must delete the 
original data set, if it still exists, using the DELETE 
command. You must then redefine the data set using the 
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DEFINE command prior to restoring it with the backup copy 
using the REPRO command. CNote that the delete and define 
operations would not be necessary if the original data set 
still exists and was defined with the REUSE attribute.) 

Using EXPORT and IMPORT to transport or back up a key-sequenced 
data set or using REPRO to copy it reorganizes the data set — it 
rearranges data records physically in ascending key sequence 
(control-interval and control-area splits might have got them 
physically out of order) and balances free space quantities. 

After you have replaced a damaged data set with its backup copy, 
you can bring the backup copy up to date with the original by 
rerunning the jobs that updated the original between the time it 
was backed up and the time it became inaccessible. 

Backing up the data sets in a user catalog enables you to 
recover from damage to the catalog. You can import the backup 
copy of a data set whose entry was lost or redefine the entry 
and reload the backup copy. If the catalog was completely lost, 
you could redefine it, then import or redefine and reload all of 
the data sets that were defined in the catalog. (Backing up the 
catalog itself is discussed in the section "Protecting VSAM 
Catalogs.") 



Exporting and Importing a Data Set 



You can use the EXPORT command (with the TEMPORARY parameter) to 
copy a VSAM cluster and its catalog entries onto a movable 
volume (that is, a demountable direct-access volume or a 
magnetic-tape volume). You can then use the IMPORT command 
either to move the portable copy to another VS1, VS2, or DQS/VS 
system that includes VSAM or to replace the original cluster and 
its catalog entries. The portable copy itself is inaccessible 
for processing. 



Making a copy of a Data Set 



You can use the REPRO command to copy a VSAM or sequential data 
set into another VSAM or sequential data set, newly defined (for 
protection) in another catalog. (The REPRO command does not copy 
the data set's catalog information.) You can use the REPRO 
command with the REPLACE parameter to merge the backup copy into 
the original data set, or you can delete and redefine the 
original data set and use REPRO to reload the backup copy into 
it. Or, because the backup copy is itself accessible for 
processing, you can replace the original with it. (You have to 
make avai lable for processing the catalog in which you defined 
the backup, and you have to use the name of the backup.) 

If you periodically process a data set sequentially, you can 
easily create a backup copy as a by-product of normal 
processing. You can use this backup copy like one made by way of 
REPRO. 



ENSURING ACCESSIBILITY OF SECONDARY EXTENTS 



When a VSAM catalog is damaged so that you have to use a backup 
copy of the catalog (see "Protecting VSAM Catalogs," below, for 
information about backing-up catalogs), any extents that were 
allocated to the catalog's data sets since the backup copy was 
made become inaccessible. 

In an entry-sequenced or a relative-record data set, the records 
in the new extents will have been added at the end. But in a 
key-sequenced data set, some of the records in the new extents 
could have been moved there because of a control-area split. 

To ensure that all of the records in a catalog's data set are 
accessible after you fall back to a backup copy of the catalog, 
you can • 
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• Eliminate the need for secondary extents in the data set by 
providing a sufficiently large primary space allocation. 

• Reduce the number of secondary extents by providing for 
sufficiently large secondary space allocations. Whenever a 
secondary extent is allocated, you can make a new backup 
copy of the catalog. You can monitor the growth of a data 
set by way of the LISTCAT command or the SHOWCB macro. (The 
use of SHOWCB to display statistics is described i n OS/VS 
Virtual Storage Access Method (VSAM) Programmer's Guide . ) 

For growth that did not require secondary allocation in a data 
set since the backup copy of its catalog was made, you can use 
the VERIFY command to reset the end-of-f i le indicators in the 
catalog after you fall back to the backup copy. 



CORRECTIVE MEASURES 



When you discover that a catastrophe destroyed part or all of 
your on-line data* you can replace the destroyed data set with 
its backup copy (if one exists) '• 

• You can use the REPRO command with the REPLACE option to 
merge the backup copy with the destroyed data. When only 
part of your data set is damaged, you can specify REPRO 
parameters that allow you to replace only the records in the 
damaged part of the data set. 

• You can use the IMPORT command to totally replace a VSAM 
cluster whose backup copy was built using the EXPORT 
command. The IMPORT command uses the backup copy to replace 
the cluster's contents and catalog information. 



PROTECTING VSAM CATALOGS 



Because you cannot gain access to a VSAM data set without the 
master or user catalog in which the data set is defined, you 
need to make sure that your catalogs can always be made 
available. You can take preventive measures to minimize the 
possibility of catalog loss and corrective measures to recover 
from loss, should it occur. 

The effect of the loss of a catalog can be minimized by the 
followi ngJ 

• Widespread use of user catalogs — a user catalog for each 
volume, where possible. (It i s not possible for multivolume 
data sets — one catalog must control all the volumes of a 
data set . ) Compare the effect of the loss of a catalog when 

(a) 10 data sets are cataloged in each of 10 catalogs and 

(b) 50 data sets are cataloged in each of 2 The fewer the 
catalogs the greater the disruption in the event of loss of 
a catalog. 

• Limited use of the master catalog. 

• Dedicated use of volumes for VSAM data sets to segregate 
VSAM and nonVSAM recovery. You can dedicate a volume by 
defining a VSAM data space that occupies the whole volume. 
If some of the space on a volume does not belong to a VSAM 
data space, OS/VS may allocate that space to a nonVSAM data 
set. If you follow a dump/restore recovery procedure 
(outlined later) you will have to fall back to a previous 
copy not only of the VSAM data and catalog, but also of the 
nonVSAM data. 



34 0S/VS2 Access Method Services 



USING REPRO TO BACK UP A CATALOG 



You can use the REPRO command to unload (make a backup copy of) 
a catalog. If the catalog becomes i naccessi ble, you can use 
REPRO to reload the copy. The section "Backing up a Catalog" in 
the chapter "Copying and Printing" describes catalog 
unload/reload. 

The backup copy might not reflect current information for some 
of the cataloged objects. The section "Updating a Backup 
Catalog" below describes how to make a backup catalog current. 



BACKING UP THE MASTER CATALOG 



An 0S/VS2 system requires a master catalog — if a system or 
hardware failure damages the master catalog, the system cannot 
be used until the damage is corrected, unless you have a backup 
master catalog. Without a copy of the master catalog, you might 
have to generate a new system (using SYSGEN processing). 

Because the system requires a master catalog, the reload 
procedure described in "Backing up a Catalog" in the chapter 
"Copying and Printing" requires modification for reloading the 
master catalog. Reloading the master catalog with REPRO works 
well, if you have a master catalog to reload and it was not 
defined as a recoverable catalog. For catalogs defined as 
recoverable, see "Restoring Catalog Entries After System 
Failure." When only some of the entries in the master catalog 
have become inaccessible, and the master catalog itself is still 
operational, you might be able to reload the backup catalog into 
it. Otherwise, you can get a master catalog by* 

• Using IEHDASDR (on another system) to restore the volume 
that contains the master catalog (from a tape onto which you 
have previously dumped the volume). You can do an IPL 
(initial program load) to bring your system up with the 
restored volume and then use REPRO to reload the backup into 
the restored version of the catalog. (If the backup is no 
more recent than the restored catalog, you can use the 
restored version without reloading.) 

With DUMP/RESTORE, you should design the volume that 
contains the master catalog to contain information that 
changes very little. Thus, you won't lose changes when you 
restore the volume. And, to avoid needing another system to 
restore the volume from a tape, you could have two 
direct-access volumes (with the same volume serial number) 
that contain a copy of the master catalog. 

• Using DEFINE (on another VS2 system) to define a user 
catalog with the same name as your master catalog. You then 
use REPRO (still on the other system) to reload the user 
catalog with the backup copy of the master catalog. You can 
bring up your system with the reloaded user catalog as your 
master catalog. 



DUMPING A CATALOG AND ITS DATA SETS 



This procedure calls for periodically dumping the volume(s) upon 
which a catalog and its data sets are stored with the IEHDASDR 
utility program (or with some other utility that achieves the 
same effect). Then, if the catalog is lost or somehow becomes 
inaccessible, you would be able to restore the volumes (or 
alternate volumes with the same volume serial numbers). The 
volumes would then contain what they contained when the backup 
copies were made. See "Updating a Backup Catalog" below about 
how to bring the restored catalog up to date. 

When you use IEHDASDR to dump a volume containing a VSAM 
catalog, you should ensure that all update activity (for 
example, DEFINE, DELETE, ALTER, data set extension, etc.) is 
quiesced. If any catalog update activity occurs during the dump 

Data Security and Protection 35 



operation* it is possible for the chain of free records in the 
catalog's low key range to be damaged in the backup copy. Then, 
if it is necessary to restore the backup copy, the damaged chain 
will be introduced into the restored copy. 

If some of the space on a volume does not belong to a VSAM data 
space, the system may have allocated that space to nonVSAM data 
sets. With DUMP/RESTORE, you will have to fall back to a 
previous copy not only of the VSAM data sets and catalog, but 
also of the nonVSAM data sets. 

When you use IEHDASDR to dump or restore a volume that contains 
VSAM objects (that is, clusters, catalogs, data spaces, and 
alternate indexes), you must include a JOBCAT or STEPCAT DD 
statement with the IEHDASDR job or jobstep to describe the VSAM 
catalog that owns the volume. The volume's table of contents 
(VTOC) indicates that part of the volume's contents is 
password-protected, and that the volume is owned by a VSAM 
catalog (that is, the passwords for the password-protected 
objects are part of the object's catalog information). However, 
the volume's VTOC does not identify the catalog that contains 
the passwords. Before a volume is dumped, the system asks the 
operator for the correct password of each password-protected 
object on the volume. However, if the volume is RACF-protected, 
RACF read authorization to the volume overrides VSAM password 
protection. For more information on how to use IEHDASDR to dump 
and restore volumes containing VSAM objects, see 0S/VS2 MVS 
Utilities. 



UPDATING A BACKUP CATALOG 



A reloaded or restored backup catalog won't reflect any changes 
in the original catalog between the time you unloaded it to make 
the backup and the time it became inaccessible. Three types of 
changes may have occurred: 

• Entries may have been deleted by way of DELETE or 
permanently exported by way of EXPORT PERMANENT. You can 
remove these entries from the backup catalog with DELETE 
NOSCRATCH, which is described below under "VSAM Catalog 
Cleanup." 

• Entries may have been defined by way of DEFINE, imported by 
way of IMPORT, or defined (nonVSAM entries only) by the VS2 
Scheduler. You can use DEFINE NONVSAM to bring the backup 
catalog up to date on nonVSAM entries. But a VSAM object 
defined by an entry missing from the backup catalog is no 
longer accessible. To regain the use of the space on a 
volume or in a VSAM data space whose entry is missing from 
the backup catalog, you can use ALTER REMOVEVOLUMES 
(described below under "VSAM Volume Cleanup"). 

To recover objects that are lost in this way, you will have 
to redefine them and rerun the jobs that loaded and updated 
them, or you will have to have backed them up as described 
above under "Backing Up Data." 

• Entries may have been updated to describe extensions. For an 
extension that used space already allocated to an object 
(that is, before the original catalog was unloaded to make 
the backup), you can use the VERIFY command to update the 
object's end-of-file indicator. But for an extension that 
used newly-allocated space, you cannot update the backup 
catalog to recover the data in the extension. (See "Ensuring 
Accessibility of Secondary Extents" above about how to 
protect yourself from this loss of data.) 
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VSAM VOLUME CLEANUP 



You normally take away the ownership of a volume from a VSAM 
user catalog by deleting all the objects and all the data spaces 
on the volume. But if a user catalog is inaccessible for some 
reason, or it no longer contains entries for the volume or its 
data spaces (as, for example, when you reload a backup catalog), 
you cannot use the DELETE command to take away ownership. 

The ALTER command with the REMOVEVOLUMES parameter enables you 
to get rid of all the VSAM data spaces on a volume without 
gaining access to the catalog that owns the volume. ALTER 
REMOVEVOLUMES overwrites the data spaces with binary zeros and 
rewrites the VTOC to remove the data spaces' format-1 DSCBs and 
to turn off the VSAM ownership bit in the format-4 DSCB. 

When the user catalog itself is on the volume, ALTER 
REMOVEVOLUMES overwrites it as well. Thus, you can use ALTER 
REMOVEVOLUMES to clean up a volume that contains a user catalog 
that has become inaccessible. You should first use EXPORT 
DISCONNECT to remove the catalog's entry in the master catalog 
prior to using ALTER REMOVEVOLUMES. 

ALTER REMOVEVOLUMES does not remove nonVSAM data sets from a 
volume, nor does it remove VSAM objects from a volume owned by 
the master catalog. See the section "VSAM Volume Recovery 
Function" for details on how to specify the ALTER REMOVEVOLUMES 
f uncti on . 

Note: 

• ALTER REMOVEVOLUMES is also used simply to take away from a 
catalog ownership of a candidate volume that does not yet 
contain a VSAM data space and is not referenced by any VSAM 
objects. 

• You should not use ALTER REMOVEVOLUMES to get rid of VSAM 
objects on a volume owned by a catalog that you can still 
use — you should use the DELETE command. 

• If you are using the ALTER REMOVEVOLUMES function for a 
volume containing a user catalog, you should make sure that 
the user catalog is not open. You can do this by including a 
DD statement (which is not a JOBCAT or STEPCAT DD statement) 
which identifies the user catalog and specifies DISP=0LD in 
the job step that includes the ALTER REMOVEVOLUMES command. 
The user catalog should not be identified in a JOBCAT DD 
statement in the ALTER REMOVEVOLUMES job, nor in a STEPCAT 
DD statement in the ALTER REMOVEVOLUMES job step, nor in any 
other DD statement(s) or Access Method Services command 
parameter(s) that would cause the catalog to be allocated 
and opened as a catalog prior to the time the ALTER 
REMOVEVOLUMES command is executed (for example, use of a 
data-set name with a high-level qualifier which is the alias 
of the user catalog). 

If the user catalog that owns the volume is available, you can 
use the DELETE SPACE command with the FORCE option to get rid of 
all VSAM data spaces on a volume whether or not they contain 
VSAM data sets. DELETE SPACE FORCE deletes all VSAM data spaces, 
marks any VSAM data sets contained therein as unusable in the 
catalog, and releases ownership of the volume. If your volume 
contains VSAM data space(s) you wish to eliminate but some VSAM 
data sets you wish to save, you can use the EXPORT command to 
export the data sets you wish to save. Then use DELETE SPACE 
FORCE to eliminate all VSAM data spaces on the volume. After 
redefining the data spaces, you can reestablish your data sets 
by using the IMPORT command. 

DELETE SPACE FORCE cannot be used for a volume that contains a 
user catalog. DELETE USERCATALOG FORCE can be used to DELETE a 
user catalog without first deleting all its entries. All data 
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spaces are deleted from each volume owned by the catalog, 
including the catalog volume itself, and volume ownership is 
released by VSAM. 



CHANGING A VOLUME'S SERIAL NUMBER 



When you change the volume serial number of a volume that 
contains VSAM objects, the VSAM objects can no longer be located 
when the objects' catalog volume information is referenced (you 
can use the LABEL statement of the IEHDASDR program to change a 
volume's serial number, or "cl i p" the volume) . You should use 
the following procedure to change the volume's serial number, to 
allow the VSAM objects on the volume to be located 1 

1. Issue the EXPORT PERMANENT command for each VSAM object 
(that is, for each alternate index and cluster) on the 
volume. When the volume also contains a VSAM catalog, issue 
an EXPORT DISCONNECT command to disconnect the user catalog 
from the master catalog. The EXPORT command copies each VSAM 
object and its catalog entry onto a movable volume. The 
object's entry in the user catalog is deleted. 

2. Issue the DELETE command to delete all empty data spaces on 
the volume, and to delete the volume entry from the catalog. 
NonVSAM data sets are described in the volume's VTOC and are 
not affected by the DELETE command. 

3. When the volume contains an empty catalog (that is, the 
catalog only describes space on the volume), delete the 
catalog. If the empty catalog describes space on more than 
its own volume, you can delete the space on each volume 
first, then delete the catalog. 

4. Execute the IEHDASDR program with the LABEL statement to 
change the volume's serial number. 

5. If the catalog was deleted in step 3, it must be redefined 
when beginning this step. Issue the DEFINE SPACE command to 
build a data space on the volume, to establish the VSAM 
catalog's ownership of the volume, and to build a volume 
entry that points to the volume with its new serial number. 
The data space you define should be large enough to contain 
all of the suballocated VSAM objects you removed from the 
volume during step 1. (When you execute the IEHDASDR 
program, you might reorganize the nonVSAM data sets 
remaining on the volume, so that the space avai lable for the 
VSAM data space is contiguous.) 

6. Issue the IMPORT command for each VSAM object that was 
removed from the volume* during step 1, specifying the new 
volume information for the object. 



VSAM CATALOG CLEANUP 



When a volume becomes inaccessible, you can use the DELETE 
command with the NOSCRATCH parameter to remove the entries for 
the VSAM objects on the volume from the catalog that owns the 
volume. You can also use DELETE NOSCRATCH to remove from a 
backup catalog entries for the VSAM objects that were deleted 
from the original catalog after the time it was unloaded to make 
the backup. DELETE NOSCRATCH removes an entry without gaining 
access to the volume indicated in the entry. You should keep in 
mind that, if the cluster, alternate index, or pagespace . was 
defined with the UNIQUE attribute, a format-1 DSCB was written 
on the object's volume. If you specify NOSCRATCH and the 
format-1 DSCB still exists, it will not be erased from the VTOC. 
(DELETE without NOSCRATCH specified allows Access Method 
Services to gain access to a volume to change the VTOC or 
overwrite an object with binary zeros.) 
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VSAM cleans up the catalog* 

• When DELETE CLUSTER, DELETE ALTERNATEINDEX, or DELETE 
PAGESPACE i s specified, by deleting the cluster, alternate 
index, or pagespace entry .' (Note: NOSCRATCH cannot be 
specifed for these entry types if they are defined in a 
recoverable catalog.) 

• When DELETE SPACE is specified, by deleting the volume 
entry. The volume entry must be empty (that is, you must 
first delete the entries of all VSAM objects that are 
indicated in the entry). 



EXPORTING A CATALOGS DATA SETS 



While the primary purpose of the EXPORT command is to allow you 
to move data sets and user catalogs between systems, it can also 
be used to create backup copies of particularly sensitive data 
sets. The EXPORT command copies a data set and extracts the data 
set's definition from the catalog in which it is defined. If you 
use Access Method Services to periodically export a data set, 
you can redefine the catalog should it be lost, define a VSAM 
data space if the data set is to be suballocated, and import the 
data set into the new catalog. With export/import you can 
control the level of each data set individually. If you exported 
a data set for backup after each run, you wouldn't have to rerun 
any jobs to bring the backup copy up to date. 

A single volume for each catalog is desirable when .your system 
contains a large number of single-volume data sets. 



MOVING A CATALOG TO ANOTHER SYSTEM 



You can move a user catalog from your 0S/VS2 MVS system to 
another system (that is, to an OS/VS or DOS/VS system that 
includes VSAM) to make the objects cataloged in the user catalog 
available to programs running on the other system. The user 
catalog might own only the volume on which it resides. In this 
case, the volume, its catalog, and its contents (that is, VSAM 
clusters, nonVSAM data sets, and free space) can be moved as a 
single unit to another system. When the catalog owns more than 
one volume, each volume owned by the catalog must either be 
moved to the other system with the catalog or be deleted before 
the catalog is moved. 

Caution: When you move a recoverable catalog to a system that 
does not support recoverable catalogs, the recoverabi 1 i ty of the 
catalog is destroyed when any of the catalog's records are 
modified, deleted, or added. 

You use the EXPORT command with the DISCONNECT option to remove 
a user catalog from its OS/VS system. The EXPORT command deletes 
the user catalog's connector entry in the system's master 
catalog. The EXPORT command also deletes all alias entries that 
point to the user catalog's connector entry. The catalog, its 
cataloged objects, and its volume(s) are now unavailable to 
users of the old system. 

When the user catalog has aliases, you should take care to list 
the aliases before you issue the EXPORT command. You can use the 
LISTCAT command to list the catalog's aliases, which are in the 
master catalog. You can use the list of aliases to help you 
reconstruct the alias entries in the new system's master 
catalog. 

You use the IMPORT command with the CONNECT option to make the 
exported catalog available to the new OS/VS system. The IMPORT 
command builds in the new system's master catalog a usei — catalog 
connector entry that points to the user catalog's volume. You 
should issue a DEFINE ALIAS command to build an alias entry in 
the new system's master catalog for each of the user catalog's 
aliases. 
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CATALOG RECOVERY 



All VSAM catalogs can be defined with the RECOVERABLE attribute 
that makes it possible to recover VSAM data sets and their 
catalog entries should the catalog be damaged or destroyed. 
Recovery is achieved by recording a copy of all catalog 
information about a given volume and its data sets on that 
volume as well as in the catalog itself. Recovery information is 
recorded on each volume owned by a catalog. Space for this 
information is automatically set aside when you acquire VSAM 
ownership of a volume and also when you define the catalog 
itself. There is no separate catalog entry for the recovery 
space*- VSAM records its physical track address in the volume's 
format-4 DSCB. 

The recovery information in the volume's catalog recovery area 
(CRA) is updated immediately whenever parallel information in 
the catalog is changed. The affected volume(s) must be mounted* 
and the kind of operation to be performed on an object (data 
space* cluster* path* etc.) determines which volume(s) to mount. 

To recover a VSAM data set and its catalog entries* you issue 
the EXPORTRA command. EXPORTRA uses the information in the CRA 
rather than the catalog to gain access to VSAM data sets and 
produce a copy of the VSAM data sets. The copy can be introduced 
back into the system by means of the IMPORTRA command. 

RESETCAT is another catalog-recovery tool. If* for any reason, 
inconsistencies develop between your catalog and the CRAs of its 
owned volumes* you should consider RESETCAT as your recovery 
vehicle. RESETCAT is basically a synchronization process between 
a catalog and its associated CRACs). If your catalog or any of 
its owned volumes becomes unusable* you can restore a backup 
volume. However* this will not solve your problems because 
inconsistencies will undoubtedly exist between your catalog and 
the CRAs of the volumes it owns. Either the catalog or the CRAs 
will be down level (entries will not precisely describe the data 
sets). RESETCAT provides the necessary synchronization facility 
to ensure consistency between the catalog and its volumes. 
RESETCAT confines its processing to the catalog and CRAs; VSAM 
data sets ar& unaffected by this operation* no data movement 
takes place. 

You can use the LISTCRA command either to list the contents of 
the CRA before you do selective recovery or to list the entries 
in the recovery area that are different from those in its 
associated catalog. 

See the "Restoring Catalog Entries After System Failure" chapter 
for more information and examples on catalog recovery. 

If you are presently using an 0S/VS2 system without recoverable 
catalogs* see Appendix H for information on making your master 
catalog recoverable. 



Regaining Access to Data 



Using some of the corrective measures listed* you can analyze 
and recover from the following conditions* 

• Inaccessible data set 

• Unusable catalog 

• Inaccessible volume 

You can use the LISTCRA command with the COMPARE option to 
identify mismatches between the catalog recovery area (CRA) and 
the catalog itself. The records in the CRA are used as a base 
for comparison and* whenever a mismatch is detected* LISTCRA 
prints the CRA record and its matching catalog record and 
identifies the mismatch by printing asteri sks below the 
mismatched area(s) of the records. (The LISTCRA command* as well 
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as EXPORTRA, IMPORTRA, and RESETCAT, is usable only with 
recoverable catalogs.) The mismatches detected by LISTCRA vary 
in their degree of seriousness. The type of mismatch determines 
the level of recovery that is required. The following list 
(ordered by severity) shows the type of mismatch, why it may 
have occurred* and how serious it is. The "Type" column 
indicates the section of the catalog record or group of fields 
in which the mismatch occurred. If the LISTCRA command detects 
more than one area of mismatch, only the most serious mismatch 
is identified. Subsequent sections of this chapter tell how to 
use corrective measures to recover. 

Figure 28 in Appendix D shows an example of the LISTCRA output 
using the DUMP COMPARE options. 
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Catalog Volume Records 
Type 



8MISC0MPARES 
Message 



DATA SPACE 
EXTENTS 



Mi smatched data 
space group 



DATA SET 
DIRECTORY 



Mi smatched data 
set directory 



VSAM Object Records 
Type 



*MISCOMPARES 
Message 



CATALOG 
ENTRY HAS 
DIFFERENT 
NAME 



VOLUME OR 
KEYRANGE 



EXTENTS 



HIGH USED 
RBA 



STATISTICS 



Mi smatched 
entryname 



Mismatched volume 
or key range in the 
volume information 
set of fields. 



Mismatched extents 
in the volume 
information set of 
fields. 



Mismatched high 
used Relative Byte 
Address 



Mi smatched 
statistics in the 
Access Method Data 
Set Statistics 
Block (AMDSB). 



Severity 

Requires recovery 

of the entire volume. 



Requires recovery 

of the entire volume, 



Requires recovery 

of the erttire volume. 

Requires recovery 
of the entire volume 



Cause 

A difference in the 
number, size, and/or 
location of VSAM 
data spaces. 

A difference in the 
number and/or 
location of extents 
for one or more 
data sets. 

Space has been 
extended or deleted. 

A difference in the 
names and/or number 
of data sets 
associated with 
thi s volume. 



Cause 

The catalog was 
restored, or the 
volume containing 
the data set was 
restored. As a 
result the record in 
the catalog pointed 
to by the CRA record 
is no longer for the 
same object. 

The catalog was 
restored, or the 
volume containing 
the data set was 
restored. As a 
result the object* s 
volume locations or 
keyranges in the CRA 
do not match those 
in the catalog. 



Data set was not Requires data set 
properly closed, the recovery, 
catalog was restored, 
or the volume 
containing the data 
set was restored. 



Severity 

Requires data set 
recovery. 



Requires data set 
recovery. 



Same as for 
mismatched extents. 



Same as for 
mismatched extents. 



Requires use of the 
VERIFY command to 
correct the high 
RBA. 

No recovery action 
is required; 
mismatched statistics 
do not affect the 
accessibility of date 
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VSAM object Records (Continued) 

XMISCOMPARES 

Message Type Cause Severity 

OTHER Mismatch of Same as for Depends on the type of 

something other mismatched extents. mismatch, 
than the above 
fields, e.g. 
passwords. 

In general, there are two types of data recovery in terms of the 
currency of the recovered data; repair and reset. 

The repair type of data recovery operation restores 
addressability and access to the most current version of the 
data. Repair operations are generally used to correct problems 
such as read and write errors associated with the data itself or 
With the data description, for example, by assigning alternate 
tracks. 

The reset type of data recovery operation restores 
addressability and access to a version of the data other than 
the most recent. Reset operations ar& generally used to correct 
logical problems such as a programming error or faulty 
transactions. Reset is generally the most common form of 
recovery, probably because of the types of problems encountered 
and the level of data available for recovery. An example of a 
reset operation is the dump (copy) and restore of .a volume. 

The following list of utility programs, whether Access Method 
Services, VSAM, or system, shows the type(s) of data recovery 
(or analysis) each program can undertake^ 

EXPORT/IMPORT Reset 

REPRO Reset/repair 

EXPORTRA/IMPORTRA Repair (recoverable catalogs only) 

COPY and RESTORE Reset 

LISTCRA (COMPARE) Analysis (recoverable catalogs only) 

DELETE UCAT(FORCE) Reset/repair 

ALTER REMOVEVOLUMES Reset/repair 

DELETE SPACE(FORCE) 

NOSCRATCH Reset/repair 
DELETE CLUSTER 

NOSCRATCH Reset/repair 

VTOC UTILITY(SUPERZAP) Reset/repair 

DELETE SPACE (FORCE) Reset/repair 

VERIFY Repair 

RESETCAT Reset/repair (recoverable catalogs 

only) 

REPRO can be used to create a backup copy of the catalog. The 
catalog can be reloaded (using REPRO) from this backup copy to 
minimize the amount of work required to accomplish recovery. The 
usefulness of a backup copy depends on what modifications have 
been made to the catalog since the backup was created, 
subsequent to taking a backup copy will affect the usefulness of 
the backup catalog: 

Altering the amount of space controlled by the catalog. The 
volume entry in the backup catalog is no longer valid and 
will mismatch with the catalog recovery area. 

Defining, altering, or deleting data sets. The volume entry 
and some of the data set entries in the backup copy are no 
longer valid. 

Suballocating space to a VSAM data set. The volume space map 
is invalidated which, in itself, is not serious. However, 
the data set entry is also invalidated, a serious problem. 
(See "Ensuring Accessibility of Secondary Extents" for more 
i nf ormat i on.) 
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Several of the recovery procedures use volume restore. If this 
is indicated, one or the other of the following must be true: 

\ 

• The volume being restored does not contain multivolume data 
sets. 

• If a volume does contain a portion of a multivolume data 
set, all volumes which contain portions of those multivolume 
data sets are treated as a single unit; that is, if a volume 
restore is required, the entire set is restored. 
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CREATING AND CATALOGING OBJECTS 



VSAM uses catalogs as a central information point for all VSAM 
data sets and the direct-access volumes on which they are 
stored. You can define a VSAM object in a VSAM catalog only by 
using the Access Method Services DEFINE command. Additionally, 
you can use the DEFINE command to define nonVSAM objects in a 
VSAM catalog. 

When you issue the DEFINE command to catalog an object, Access 
Method Services builds a catalog entry to describe the object. 
The VSAM objects you can define are: 

• User catalog, which is a collection of information about 
nonVSAM objects, and about VSAM objects that reside on the 
volumes owned by the user catalog. You can create a user 
catalog at any time. A pointer to the user catalog is put in 
the system's master catalog. A master catalog is created 
during the SYSGEN process. The VSAM master catalog is the 
0S/VS2 system's primary catalog. 

• Data space, which is direct-access device space used for a 
catalog, for VSAM clusters, for page spaces, and for 
alternate indexes. VSAM controls the allocation of space 
within each data space. 

• Cluster, or VSAM data set, which is a collection of 

user — data records. There are three types of cluster data 
organi zati on: 

Entry-sequenced, or sequential, in which data records 
are read or written sequentially from one end to the 
other (first to last for writing, either direction for 
readi ng) . 

Key-sequenced, or indexed, in which a data record is 
read or written based on its key value. A key is a 
field, shorter than and within the record, that 
identifies the record. 

Relative-record, or direct, in which a data record is 
read or written based on its relative-record number — its 
displacement, in records, from the beginning of the 
cluster. 

• Alternate index, which allows you to read and write data 
records in an entry-sequenced or key-sequenced cluster 
(called the base cluster) based on an alternate key. 

• Path, which is a data-set name for the combination of an 
alternate index and its base cluster, or an alias for a VSAM 
cluster. A path entry can be password protected. 

• Page space, which is an amount of direct-access device space 
to be used exclusively by the 0S/VS2 system. 

The nonVSAM objects you can define are : 

• NonVSAM data set, which is a collection of data records with 
sequential, partitioned, direct, or i ndexed-sequent i al data 
organisation (that is, not VSAM data organization). 

• Generation data group, which is a collection of nonVSAM data 
sets that are grouped together in a time-dependent manner. 

• Alias, which is an alternate name for a user catalog or 
nonVSAM data set. 
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Before an object can be defined* you must have a VSAM catalog in 
which to define the object. Every 0S/VS2 system must have a VSAM 
master catalog before initial program load (IPL) is done for the 
system. 

When you define an object, you specify attributes to be 
associated with it. The attributes include, for example, any 
passwords required to use data and how space is to be allocated. 
After the object is defined, it can be processed with other 
Access Method Services commands and with the user's VSAM 
program. After a cluster is defined, for example, you can load 
data records into it by using the REPRO command. 

VSAM clusters, alternate indexes, page spaces, and catalogs are 
stored in data spaces. You can allow a data space to contain 
many VSAM objects by simply not specifying otherwise (the usual 
case and the default), or you can restrict a data space so that 
it contains only one VSAM object. In the usual case, you define 
a data space first, then define the data sets. To define a VSAM 
object as the only one in its data space, specify the parameter 
UNIQUE when you define the data set. When the object is defined, 
VSAM allocates a unique data space and assigns it to the object. 

Refer to the chapter: "Command Format" for a description of the 
command format for DEFINE USERCATALOG. Examples of defining user 
catalogs are also included. 



PREVENTING DUPLICATE NAMES IN CATALOGS 



With multiple catalogs (the master catalog, user catalogs, and 
OS/VS CVOLs), you should take care so that a data-set name in 
one catalog is not duplicated in another catalog. It is possible 
to have the same data-set name in more than one catalog. 

Access Method Services prevents you from cataloging two objects 
with the same name in the same catalog, and from altering the 
name of an object so that its new name duplicates the name of 
another object in the same catalog. However, this does not 
prevent duplication of names from one catalog to another. A 
following section, "Order of Catalog Use: DEFINE," describes the 
order in which one of the catalogs available to the system is 
selected to contain the to-be-defined catalog entry. When you 
define an object, you should ensure that the catalog the system 
selects is the catalog you want the object's entry in. 

Additionally, duplication is not prevented when a user catalog 
is imported into a system; no check is made to determine whether 
the imported catalog contains a name that another catalog 
already in the system contains. 



JCL AND DYNAMIC ALLOCATION CDEFINE) 



Defining an object does not normally require that a volume be 
mounted, because the availability of space in data spaces can be 
determined by examining the volume information in the catalog. A 
volume must be mounted whenever its VTOC has to be consulted or 
modified, that is, when a data space, a unique data set, or a 
catalog i s fcei ng def i ned. If the catalog in which the object is 
being defined is recoverable, the volume containing the catalog 
recovery area to be updated must be mounted. (Refer to the 
section "Restoring Catalog Entries After System Failure" for a 
description of the catalog recovery volume.) Before a system 
component, such as VSAM or Access Method Services, can process a 
data set or volume, the OS/VS system allocates the data set or 
volume to the system component. Usually, the data set or volume 
is allocated to the system component when the OS/VS Scheduler 
processes your job control language (JCL) DD statements. 

However, when a data-set name or volume-serial number is 
specified with an Access Method Services command, but its data 
set or volume has not been described with a DD statement, the 
data set or volume is allocated dynamically. The information 
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describing a data set that the DD statement would have provided 
is extracted from the data set's entry in the catalog. This type 
of allocation is called dynamic allocation. The data-set's 
volume should be mounted as permanently resident or reserved to 
ensure successful dynamic allocation. 

If JCL is used to allocate a volume, include a DD statement of 
the forms 

//ddname DD UNIT=( typeC ,uni tcount 3 C , DEFER] ) , 
// V0LUME=SER=(serialC,serial2,. . . ]),DISP=OLD 

• UNIT= can specify a device type and volume-serial number for 
any direct-access storage device that is supported by your 
OS/VS system. 

• VOLUME=SER= indicates the serial number(s) of the volume(s) 
on which data spaces are to be allocated. When more than one 
volume is indicated, all volumes must be of the same device 
type. 

• DISP=0LD is required because VSAM allocates space to VSAM 
objects (that is, catalogs, clusters, alternate indexes, and 
page spaces) . When you code DISP=NEW, the OS/VS system 
allocates space to the object. The space that the system 
allocates is not recorded in the object's catalog entry. 
Unless the object is a nonVSAM data set, the space allocated 
by the system is not available for the object's use. 

ORDER OF CATALOG USE: DEFINE 

The order in which catalogs are used when an entry is defined 
i s- 

• If a catalog is specified in the CATALOG parameter, that 
catalog is selected to contain the to-be-defined entry. 

• When a nonVSAM generation data group (GDG) data set is 
defined, the catalog containing the GDG base is selected to 
contain the to-be-defined nonVSAM entry. Otherwise, 

• The first user catalog specified in the current job step 
(STEPCAT) or, if none is specified for the job step, the 
first user catalog in the current job (JOBCAT) is selected 
to contain the to-be-defined entry. (The section "JOBCAT and 
STEPCAT DD Statements" describes how you can specify a user 
catalog for the current job step or current job.) Otherwise, 

• If no user catalog is specified for the current job step or 
job, and the entry's name is a qualified name, and the first 
qualifier (that is, the first one to eight characters before 
the period) is the same as : 

the name of a user catalog, or 

the alias of a user catalog, 

the catalog so identified is selected to contain the 
to-be-defined entry. 

• If no catalog has been identified, either explicitly or 
implicitly, VSAM defines an object in the master catalog. 

THE DEFINE COMMAND: HOW PARAMETERS ARE ORGANIZED 

When you define a catalog, cluster, or alternate index, you can 
specify attributes in several different ways. The parameter set 
for DEFINE USERCATALOG, CLUSTER, and ALTERNATEINDEX is directly 
related to the way in which the attributes are stored in the 
VSAM catalog. The catalog entries which describe a VSAM catalog, 
cluster, or alternate index ar& : 
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• The cluster entry, which describes attributes pertaining to 
the cluster or catalog as a whole; these are primarily 
protection attributes. 

• The alternate index entry, which describes attributes 
pertaining to the alternate index as a whole; these are 
primarily protection attributes. 

• The data entry, which describes attributes pertaining to the 
data component of a catalog, cluster, or alternate index. 

• The index entry, which describes attributes pertaining to 
the index component of a catalog, key-sequenced cluster, or 
alternate index. 

When you specify attributes as parameters of USERCATALOG, 
CLUSTER, or ALTERNATEINDEX, they are defined in the VSAM catalog 
in the cluster or alternate index entry if they pertain to that 
entry; for example, protection attributes. However, when you 
specify attributes as parameters of USERCATALOG, CLUSTER, or 
ALTERNATEINDEX which pertain to the data and/or" i ndex entries, 
Access Method Services directs the attributes to the proper 
entry. For example, if you specify the WRITECHECK attribute as a 
parameter of CLUSTER, it will not be defined in the CLUSTER 
entry but will be entered in the DATA entry and the INDEX entry 
in the catalog. When you specify attributes as parameters of 
DATA or INDEX, they are defined in the VSAM catalog directly in 
the data or index entry. You may use the LISTCAT command with 
the ALL option to list catalog entries and determine where the 
various attributes are stored in the catalog. "Appendix B: 
Interpreting LISTCAT Output Listings" describes the various 
attributes for each type of entry. 

Except for protection attributes, if you specify the same 
attribute as a subparameter of USERCATALOG, CLUSTER, or 
ALTERNATEINDEX and also as a subparameter of DATA and/or INDEX, 
the value of the attribute specified at the DATA/INDEX level 
overrides the value of the attribute specified at the 
USERCATALOG, CLUSTER, or ALTERNATEINDEX level. 

Since Access Method Services directs the attributes you specify 
to the proper entry, you do not need to specify any attributes 
as parameters of DATA or INDEX. However, you may wish to specify 
attributes as parameters of DATA and INDEX if you wish to : 

• Specify a name for the data and index components of a 
cluster or alternate index. 

• Specify unique protection attributes for the data and index 
components of a cluster or alternate index. 

• Specify space allocation for the data component only or for 
the data and index components separately of a catalog, 
key-sequenced cluster, or alternate index. 

• Specify volumes of a different device type for the data and 
index components of a key-sequenced cluster or alternate 

i ndex. 

• Specify a different variation of the same attribute for the 
data and index components of a catalog, key-sequenced 
cluster, or alternate index. For example, you may wish to 
specify WRITECHECK for the data component and NOWRITECHECK 
for the index component or vice versa. 

The level at which you specify attributes can also be affected 
if you use the MODEL parameter of the DEFINE command (see "How 
to Use One Object as a Model for Another Object"). 
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HOW TO USE ONE OBJECT AS A MODEL FOR ANOTHER OBJECT 

You can use the entry of an already-defined VSAM object (that 
is> an already-defined alternate index, catalog, cluster, or 
path) as a model for the definition of another object of the 
same type. When one entry is used as a model for another, its 
attributes are copied as the new entry is defined. 

You can override some of the model's attributes by explicitly 
specifying them with the DEFINE command. If you do not want to 
change or add any attributes, you need only supply the entryname 
of the object being defined and the MODEL parameter. (When you 
define a catalog, you must also specify the catalog's volume and 
space information, because the catalog, when defined, owns the 
volume. When you define an alternate index or a path, you must 
also specify the object to which it is related.) 

• If MODEL is specified as a parameter of USERCATALOG, 
PAGESPACE, or PATH: 

the attributes of the model are copied for the object 
being defined, then 

any attributes explicitly specified as parameters of 
your DEFINE command override those of the model. 

• If MODEL is specified as a parameter of CLUSTER or 
ALTERNATEINDEX (that is, at the cluster level) but is not 
specified as a subparameter of the DATA or INDEX parameter* 

the attributes of the model are copied for the cluster 
or alternate index entry of the object being defined, 
then 

any attributes explicitly specified as parameters of 
CLUSTER or ALTERNATEINDEX override those of the model 
for the cluster or alternate index entry. 

the attributes of the model's data and index components 
are copied for the object's data and index components, 
then 

attributes explicitly specified as parameters of CLUSTER 
or ALTERNATEINDEX are propagated to the data and index 
components, overriding those of the model, then 

attributes explicitly specified for the object's data 
and index components (that is, specified as 
subparameters of the DATA or INDEX parameter) override 
the previous two steps. 

• If MODEL is specified as a subparameter of DATA or INDEX as 
well as a parameter of CLUSTER or ALTERNATEINDEX: 

- the attributes of the CLUSTER or ALTERNATEINDEX model 
are copied for the cluster or alternate index entry of 
the object being defined, then 

any attributes explicitly specified as parameters of 
CLUSTER or ALTERNATEINDEX and override those of the 
model for the cluster or alternate index entry. 

attributes explicitly specified as parameters of CLUSTER 
or ALTERNATEINDEX are propagated to the object's data 
and index components, then 

attributes of the model specified for the data or index 
component are copied (that is, the model specified with 
the MODEL subparameter of the DATA or INDEX parameter), 
overriding the previous step, then 
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attributes explicitly specified for the data and index 
components are copied (that is, the attributes specified 
with subparameters of the DATA or INDEX parameter), 
overriding the previous two steps. 

The MODEL parameter is designed to let you easily define data 
sets that Qr& essentially identical. By explicitly specifying 
certain parameters (for example, protection attributes), you can 
override any attributes of the model you wish to change. When 
you use the MODEL parameter, you should take care to ensure that 
your job is not terminated because of allocation problems when 
you explicitly do any of the following 1 

• Specify a different type of device with the VOLUMES 
parameter. 

• Change the length or position of the keys with the KEYS 
parameter. 

• Change the size of records, buffer space, or control 
intervals with the RECORDSIZE, BUFFERSPACE, or 
CONTROLINTERVALSIZE parameters. 

• Change the type of cluster (that is, entry-sequenced, 
key-sequenced, or relative-record), the type of alternate 
index (that is, key-pointer or RBA-poi nter) , or the 
allocation-type of the object (that is, unique or 
nonuni que) . 

• Change the unit of allocation with the CYLINDERS, RECORDS, 
or TRACKS parameters. 

When you explicitly specify any of the above parameters for your 
to-be-defined object, you might have to make corresponding 
changes to other related parameters. 



DEFINING A CATALOG 



The DEFINE command can be used to define user catalogs. 

A master catalog, which is the system catalog, is established at 
system-generation time. The volume on which the master catalog 
is defined must be permanently mounted. The master catalog is 
selected for use at initial program load (IPL) time. Because the 
master catalog is created at system-generation time and because 
only one master catalog is allowed on a system, you cannot issue 
DEFINE MASTERCATALOG to create a master catalog in a VS2 system. 
If you issue DEFINE MASTERCATALOG, VSAM creates a user catalog. 
You can, however, establish a user catalog as a master catalog 
at IPL time. See "Appendix H: Changing the Attributes of the 
VSAM Master Catalog" for a description of this procedure. 

In a system with the Mass Storage System, a user catalog can be 

defined on a mass storage volume. If it is, it is staged and 

bound when it is opened (that is, it is retained until closed on 

the direct-access storage staging drive to which it is staged). 

A catalog can contain entries for both objects stored on mass 
storage volumes and objects stored on direct-access storage 
volumes. 

User catalogs are pointed to by the master catalog. The master 
catalog contains a usei — catalog entry that identifies the user 
catalog's volume. Each user catalog resides on a different 
volume. All VSAM objects on a volume must be defined in the 
volume's user catalog. A user catalog can control (that is, 
catalog the objects of) more than one volume. 

When you define a user catalog, you can specify passwords for it 
even when the master catalog is not password-protected. To 
prevent an unauthorized user from deleting your user catalog, 
specify a password for it (the catalog's master password is 
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required to delete it, but any password specified for the 
catalog results in a master password). (See the MASTERPW, 
CONTROLPW, UPDATEPW, and READPW descriptions.) 

You can delete a user catalog and redefine it in the same step, 
but you cannot use it in that step. A TSO session is considered 
one step so you would have to log off and log on to use a 
catalog that you had deleted and redefined. 

Note'* When a new user catalog has been defined, the first object 
cataloged causes the initialization of the entire catalog to 
take place. It also reserves the volume on which the catalog 
resi des. 



HOW SPACE IS ASSIGNED TO A CATALOG 



The structure of a VSAM catalog is described in Planning for 
Enhanced VSAM Under OS/VS . Familiarity with this structure will 
be of help to you in understanding the discussion that follows. 

When a catalog is defined, the catalog is the first VSAM object 
contained on the volume. VSAM first builds a data space on the 
volume and then builds the catalog itself (see the section 
"Defining a Data Space" for further information about VSAM data 
spaces). You must specify the size of the data space by using 
the CYLINDERS, RECORDS, or TRACKS parameter as a subparameter of 
USERCATALOG. For example, 

DEFINE USERCATALOG - 
TRACKSCprim seen)...) 

where? 

• TRACKS specifies the number of tracks to be allocated to the 
data space. 

You may optionally specify the size of the catalog itself by 
using the CYLINDERS, RECORDS, or TRACKS parameter as a 
subparameter of DATA, or DATA and INDEX. For example, 

DEFINE USERCATALOG - 

(TRACKS (prim seen)...) - 
DATA - 

(RECORDS(prec srech.J 

where* 

• TRACKS specifies the number of tracks to be allocated to the 
data space. 

• RECORDS specifies the number of records to be contained in 
the low-key range of the catalog's data component (see the 
section "Estimating the Catalog's Space Requirements" for a 
discussion of this value). 

The data space is built for the catalog's exclusive use when the 
DATA and INDEX parameters do not include space subparameters. If 
the DATA or DATA and INDEX parameters do include space 
subparameters, part of the data space can contain suballocated 
VSAM data sets. 

To share the data space with other VSAM data sets, you can 
specify space for the data and, optionally, index components of 
the catalog. The space specified as a subparameter of DATA and 
INDEX determines the amount of space used by the catalog; the 
space specified as a subparameter of USERCATALOG determines the 
amount of space in the data space. If space is specified for the 
low-key range of the data component (using the DATA parameter) 
but not for the index component, VSAM determines the amount of 
space required for the catalog's data component high-key range, 
the sequence set, and for the index component. 
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The following is a summary of the three ways in which space can 
be specified when defining a catalog. 

• If DATA space subparameters ar& not coded* the entire data 
space is allocated to the catalog in multiples of allocation 
units. Any remaining space that is not a multiple of an 
allocation unit is available for suballocat i on by other VSAM 
data sets. (INDEX space subparameters are invalid unless 
DATA space subparameters are also specified.) 

• If both DATA and INDEX space subparameters are coded, the 
sum of the space subparameters determines the amount of 
space available to contain the catalog. VSAM determines the 
proportion of this amount of space to be allocated to the 
catalog's data and index component^. The remainder of the 
data space is available to contain suballocated VSAM data 
sets. 



If DATA space subparameters are coded but 
subparameters are not coded, the amount s 
the size of the low-key range of the cata 
component. VSAM then determines the amoun 
for the high-key range of the data compon 
set, and the high-level index and adds it 
subparameter specification. That is, VSAM 
additional space needed based on the amou 
specified for the low-key range of the ca 
component. The remainder of the data spac 
space that is not allocated to either the 
i ndex -components) is available to contain 
data sets. 
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For example, if you specified, as a subparameter of USERCATALOG, 
100 cylinders of a 3330 Disk Storage Device (that is, the 
primary allocation for the catalog's data space is 100 
cylinders) and for the catalog's data and index components 5 
cylinders (that is, the sum of the DATA and INDEX primary 
allocation amounts is 5 cylinders), 95 cylinders remain in the 
data space and are available for suballocated VSAM data sets. 

Catalog space is allocated in tracks (even when you specify 
cylinders or records). The number of tracks is a multiple of an 
allocation unit. An allocation unit is the size of a control 
area, with one track for the control area's replicated 
sequence-set record. The size of an allocation unit is ; 

• 3 tracks for a 3380, 3375, 3350, 3330, 3330 model 11, or 
2305 model 2 (2 tracks for the control area and 1 track for 
the sequence set record) 

• 4 tracks for a 2305 model 1 (3 tracks for the control area 
and 1 track for the sequence set record) . 

• 5 tracks for 2314/2319 or 3340/3344 (4 tracks for the 
control area plus 1 track for the sequence set record). 

When the amount of space you specify is not a multiple of the 
device's allocation unit, the amount of space is rounded 
downward to a multiple and the additional tracks are not used. 
If you specify less than the minimum allocation unit, the amount 
of space is rounded upward and a minimum-sized catalog is 
allocated. 

One allocation unit is always allocated to the index set of the 

index. Ten percent of the remaining allocation units (or at 

least one allocation unit) is allocated to the high-key range of 

the data component. The rest of the allocation units ar& 
allocated to the low-key range. The minimum catalog size is 

three allocation units : one each for the index set, the high-key 
range, and the low-key range. 
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For example, assume that one cylinder on a 3330 is specified for 
the entire catalog (1 cylinder = 19 tracks): 

• The number of tracks is rounded down to 18 tracks, which is 
six allocation units of three tracks each (the nineteenth 
track is not used and not available unless the catalog's 
data space is suballocated) . 



One allocation unit 
catalog's index set 



(three tracks) is allocated to the 



Because 10% of the remaining 15 tracks is less than three 
one allocation unit is allocated to the high-key 
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(Records in the high-key range are 



• The remaining four allocation units (12 tracks) ar& 

allocated to the low-key range of the data component. Each 
allocation unit includes one track for the replicated 
sequence-set record and two tracks for a control area with 
40 control intervals, which can hold 40 records. (Records in 
the low-key range are- 505 bytes long.) The low-key range can 
hold a maximum of 160 records. From 12 to 15 of these 
records (13 for a 3330) are used to describe the catalog 
i tself . 

When the maximum number of records is reached in the low-key or 
high-key range, the catalog must be extended to hold additional 
records. When you define the catalog, you can specify an amount 
of space for secondary allocation. 

It may be desirable in some cases to have the high-key range 
allocated 20% of the data component space, rather than the 
normal 10%. If the SPACE subparameter is specified on both DATA 
and INDEX, and the specified INDEX quantity is exactly 20% of 
the specified DATA quantity, then the high-key range will be 
allocated 20% of the space available for the data component. 

DEFINE USERCATALOG( - 
NAME(USERCAT) - 
FILE(DDX) - 
VOLUME(USEROl) - - 
CYLINDERS(60 5)) - 
DATA( - 

CYLINDERS(50 5)) - 
INDEX( - 
CYLINDERS(IO)) 

Sixty cylinders are to be allocated to the catalog's data space. 
Since space is specified on both DATA and INDEX, the index value 
is exactly 20% of the data value, the high-key range will be 
allocated 20% of the space available for the data component. 



IDENTIFYING THE CATALOG'S VOLUME 



When you define a catalog, you can use a JCL DD statement to 
identify and mount the volume on which the catalog is to reside. 
Instead of using a JCL DD statement, you can rely on dynamic 
allocation to identify the catalog's volume. The volume must be 
mounted as permanently resident or reserved. If JCL is used, 
include a DD statement of the form: 

//ddname DD DISP=OLD,UNIT=( typeC ,, DEFER]) , 
// VOLUME=SER=serial 

The volume on which the catalog and its data space are to be 
allocated must be mounted, because the data space must be 
described in a data-set control block (DSCB) that is stored in 
the volume's VTOC (volume table of contents). The DSCB is added 
to the VTOC and the volume-ownership information, also in the 
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VTOC, is reset to indicate that the volume is owned by a VSAM 
catalog. VSAM determines whether the space is available on the 
volume and, if so, formats a DSCB for the data space. 

NONVSAM DATA SETS AND THE CATALOG'S UPDATE PASSWORD 

When you expect the user catalog to contain nonVSAM data sets, 
you should take care when you specify passwords for the catalog. 
When you specify an update password* for the catalog, Access 
Method Services requires that you supply the password whenever 
you (or another user) want to alter or delete one of the 
catalog's nonVSAM data sets. You can protect the catalog against 
unauthorised usage by specifying a master password. See the 
UPDATEPW description under DEFINE USERCATALOG for more details 
about how a catalog's update password is used. 

ESTIMATING THE CATALOG'S SPACE REQUIREMENTS 

Before you define a catalog, you should estimate the amount of 
space needed for the catalog's data component. To determine the 
approximate number of records required for the low-key range of 
the catalog, use the worksheet in Figure 3s 
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Variable Quantities 



Formulas 



Estimates 



Basic requirement = 10 records 



A 1 = 



B 1 - 

C = 

D = 

E = 

F = 

G = 
H 
I 
J 



number of key-sequenced clusters 
number of key-sequenced clusters with alternate 
indexes to be upgraded 
number of entry-sequenced clusters 
number of entry-sequenced clusters with alternate 
indexes to be upgraded 
number of relative-record clusters 
number of alternate indexes 
number of path entries 
number of nonVSAM data set entries 
number of generation data group entries 
number of alias entries 
number of pagespaces 

number of volumes, depending on device type, 
owned by the catalog: 
J ' = number of 2305 volumes 
J 2 = number of 2314/2319 volumes 
J 3 = number of 3330 and 3340/3344 volumes 
J 4 = number of 3330 Model 1 1 and 3350 volumes 
for each key-sequenced cluster and alternate index 
(KSDS) with space on more than two volumes, 
add "1" for each additional group of one to five 
volumes: 

K 1 = number of KSDSs with 3 to 7 volumes 
K 2 = number of KSDSs with 8 to 1 2 volumes 
K 3 = n&mber of KSDSs with 1 3 to 1 7 volumes 
for each entry-sequenced cluster and relative-record 
cluster (ESDS) with space on more than five volumes, 
add "1 " for each additional group of one to eight 
volumes: 

L 1 = number of ESDSs with 6 to 13 volumes 
L 2 = number of ESDSs with 14 to 21 volumes 
for each group of four data spaces on a volume, 
add "1" 

number of entry records required for the catalog's 
data component (total of A through M above) 



Ax3 
A*x4 



Bx2 
B*x3 



Cx2 

Dx3 

E 

F 

G 

H 

1*2 



J'x2 
J 2 x3 
J 3 x4 
J 4 x6 



K 2 x2 
K 2 x3 



L 2 x2 
M 

N 



10 



Figure 3. Worksheet for Estimating a Catalog's Space 
Requi rements 



When you define the catalog's space parameters, you may use one 
of the formats shown below- 

1. If you wish to assign all of the space to the catalog 
itself, you may specify: 

DEFINE USERCATALOG - 

(TRACKStprim seen)...) 



where 



prim = the amount of space for the primary extent (that 
is, allocation) of the catalog's data space. You can 
calculate the minimum value of prim as : 

prim = (aN + b) tracks 
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where N is the value derived from the worksheet (Figure 
3) and the values of a and b are derived from the table 
below : 

Catalog resides on: a fa 



2305 


Model 1 


0. 


.1 


5 


2305 


Model 2 


0. 


.09 


3 


2314 


or 2319 


0. 


.1364 


5 


3330 


or 3330-11 


0. 


.09 


3 


3340 


or 3344 


0, 


.125 


5 


3350 




0. 


.0667 


3 



The calculated value of prim should be rounded upward to 
a whole number of tracks. 

• seen = the amount of space for each secondary extent of 
the catalog's data space. 

This example shows the space specification in terms of 
TRACKS using the worksheet in Figure 3. Vou may also 
specify the value for prim and seen as a subparameter of 
CYLINDERS. 

If you wish to have other VSAM objects in the catalog's data 
space, you may specify* 

DEFINE USERCATALOG - 

(TRACKS(prim seen)...) - 
DATA - 

(RECORDS(prec srec ...) 



where ; 



prec = the number of catalog entry records in the 
low-key range, or the value of N from the worksheet 
(Figure 3). VSAM uses this value to calculate the total 
primary allocation requirements for the catalog itself. 

srec = the number of catalog-entry records to be used by 
VSAM to calculate the catalog's secondary-extent 
allocation. 

prim = the total amount of space for the primary extent 
of the catalog's data space. The amount of space 
assigned to the catalog itself is taken from the prim 
space as calculated by VSAM from the value specified by 
prec. You can determine the amount of space that VSAM 
calculates for the catalog itself using the following 
algorithm 2 

(aN + b) tracks 

as described for format-1 above. When you specify a 
value for prim larger than the requirements for the 
catalog itself, the remainder of the space is available 
for the suballocat i on of other VSAM objects. Using this 
format, you may also specify the value for prim as a 
subparameter of CYLINDERS rather than TRACKS. 

seen = the amount of space to be used for each secondary 
extent of the catalog's data space. 



The catalog's secondary Allocation Amount 



You should specify a secondary allocation amount for the 
catalog's data component. You cannot use the ALTER command to 
add or change a secondary allocation amount once the catalog is 
defined. 

The secondary allocation quantity is allocated each time one of 
the catalog's key ranges needs more space — up to a total of 
thirteen times. The secondary allocation quantity you specify 



56 0S/VS2 Access Method Services 



for the catalog's data component applies to the catalog's 
high-key range and low-key range (including their sequence set 
tracks). When the high-key range or low-key range runs out of 
space> the specified secondary allocation quantity is allocated 
to the key range that requires the space (when both key ranges 
run out of space at the same time, two separate extents are 
allocated 1 one for each key range, and each equal to the 
secondary allocation quantity). 

You use the secondary allocation to minimize the size of the 
low-key range and to provide for an extension of the high-key 
range 1 after the catalog's index set is allocated, 10% of the 
remaining space (or one allocation unit, whichever is larger) is 
allocated to the high-key range; the remainder of the catalog's 
space is allocated to the low-key range. However, the high-key 
range might achieve only 25% utilization. Rather than specify a 
primary allocation quantity large enough to allow for low 
utilization of the high-key range and, therefore, create an 
unnecessarily large low-key range, you can specify a secondary 
allocation. The secondary allocation quantity is allocated to 
the high-key range when it requires space, without affecting the 
size of the low-key range. (The same applies to the low-key 
range, when it requires space.) 

The high-level index of a catalog never requires extension. 

Space Allocation for tha Catalog Recovery Area (CRA) 

Whether or not a catalog is defined with the RECOVERABLE option 
has a bearing on how space is assigned in the catalog. For a 
recoverable catalog, VSAM creates a catalog recovery area (CRA) 
on each volume owned by the catalog. The primary allocation for 
a CRA is the number of tracks equivalent to one cylinder. VSAM 
ensures that these tracks are contiguous, but they may or may 
not start on a cylinder boundary. On the volume on which the 
catalog resides, the primary allocation for the CRA is allocated 
from the catalog's data space. 

On volumes without a VSAM catalog, a primary space allocation is 
obtained by VSAM for the CRA when the first data space is 
defined on the volume. If the first data space is defined via 
the UNIQUE attribute of DEFINE CLUSTER or ALTERNATEINDEX, VSAM 
obtains one cylinder of space on the volume for the CRA. In 
| other words, the CRA's primary and secondary allocation is added 
to the space specified via space parameters (CYLINDERS, RECORDS, 
or TRACKS) of your DEFINE command. 

If the first data space is defined via DEFINE SPACE, VSAM first 
attempts to obtain space for the CRA's primary and secondary 
allocation as before. However, if VSAM fails to obtain the 
space, the CRA will be allocated from the space specified via 
the space parameters. If the first DEFINE SPACE for a volume 
specifies the CANDIDATE attribute, VSAM obtains one cylinder for 
the CRA's primary and secondary allocation. 

Once a primary allocation of the CRA is filled, it can expand to 
include a maximum of 15 additional extents. The allocation for 
each secondary extent is one cylinder. 



DEFINING A DATA SPACE 

The DEFINE command can be used to define VSAM data spaces or to 
reserve volumes for future VSAM use. 

Refer to the chapter 1 "Command Format" for a description of the 
command format for DEFINE SPACE. An example of defining a VSAM 
data space is also included. 
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VSAM DATA SPACES ON A VOLUME 



A VSAM data space is space on a direct access volume that is 
owned and managed by VSAM (as opposed to space managed by OS/VS 
using Direct-Access Device Space Management— DADSM) . All of the 
data spaces (and VSAM data sets) on a volume ar& defined in the 
same VSAM catalog. When you define the volume's first data space 
(or you specify the volume as a candidate to contain VSAM 
objects) you ar<a, in effect, giving control over the volume to 
the catalog that contains the data space entry. All future data 
spaces and VSAM objects on that volume must be defined in the 
defining catalog (that is, the catalog that describes the 
volume's first-defined data space). Remember that when you 
define a catalog you cause the first data space to be defined on 
the catalog volume. 

A VSAM data space may include several extents on the same 
volume, but it cannot span volumes. The volume that contains the 
data space is owned by the catalog that contains the catalog 
entry for the space. A VSAM data space can take up all or part 
of the space of a direct-access volume. It cannot take up space 
on more than one volume. There can be more than one data space 
on a volume. In a system with the Mass Storage System, a data 
space can be defined on a mass storage volume. 

When you define a data space, you must specify the volume that 
is to contain the data space. When you specify more than one 
volume, a data space of the size you specify is allocated on 
each volume; each volume comes under the control of the defining 
catalog. Access Method Services creates a volume entry in the 
catalog to describe each volume on which one or more data spaces 
have been defined. 

If there is space available and.there is no volume ownership 
conflict, a VSAM data space is allocated on the volume. When the 
data space is the first data space on a volume, VSAM ownership 
is indicated in the VTOC. The volume's VTOC is modified so that 
an ownership indicator is set in the format-4 DSCB. A format-1 
(identifier) DSCB describing the data space is also written into 
the VTOC. When the data space is the first data space on a 
volume owned by a recoverable catalog, VSAM also allocates a 
recovery space on the volume. Refer to "Space Allocation for the 
Catalog Recovery Area (CRA)" for more information on CRA space 
allocati on. 



Allocating the Volume 



You can use a DD statement to allocate the volume on which the 
data space is to be defined. If you do not use a DD statement to 
allocate the volume, the volume identified with the VOLUMES 
parameter is dynamically allocated. The volume must be mounted 
as permanently resident or reserved. 

When you use a DD statement to allocate the volume on which the 
data space is to be defined, it should be in the form : 

//ddname DD DISP=OLD, 

// UNIT=(devtypeC,unitcount3[, DEFER]), 

// VOLUME=SER=(volserlt, volser2, . . . 3 ) 



VSAM OBJECTS IN A DATA SPACE 



All VSAM objects (that is, catalogs, clusters, alternate 
indexes, and page spaces) are stored in VSAM data spaces. A 
unique component is defined as the only component in its data 
space. VSAM allocates the data space for a unique component when 
you define the data set. A nonunique object can share a data 
space with other VSAM objects. That is, a catalog, clusters, 
page spaces, and alternate indexes might also be in the data 
space. To define a data set that can share a data space with 
other data sets, a data space must have been defined beforehand 
in which to suballocate space for the data set. 
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A data space can contain many nonunique data sets, and a data 
set can be stored in more than one data space, on the same 
volume or on different volumes. 



SPACE ASSIGNMENT TO VSAM OBJECTS 



When VSAM allocates space for a new data set or extends the 
space for an existing data set, it allocates the space from that 
available in a data space. For a new data set, if not enough 
space is available, the DEFINE fails, and you must define a data 
space with sufficient space. 

For an existing data set, if not enough space is available, VSAM 
tries to extend the data space. If the data space cannot be 
extended (it may already have the maximum number of extents or 
there may not be enough space on the volume), VSAM tries to set 
up a new data space on the same volume as the old. 

If the data space cannot be extended because a suballocated data 
set's secondary allocation amount is greater than the data 
space's secondary allocation amount, VSAM builds a new data 
space*, its primary and secondary allocation amounts are the same 
as the data set's secondary allocation amount. Consequently, the 
total amount of space allocated to VSAM data spaces on a volume 
might exceed the predicted limit. If there is not enough space 
on the volume and you identified another volume for expansion 
when you defined the data set, VSAM tries to set up a data space 
on that volume. 



DEFINING A CLUSTER 



The DEFINE command can be used to define a catalog entry and 
allocate space for an indexed, nonindexed, or relative-record 
cluster. When a DEFINE command is used to define a cluster, as 
many as three entries are created in the catalog* an entry for 
the cluster, its data component, and, if the cluster is indexed, 
its index component. 

Attributes of components can be specified separately from the 
attributes of the cluster. If attributes are specified for the 
cluster as a whole and are not specified for the components, the 
attributes of the cluster (except for its passwords and other 
protection attributes) apply to its components. If an attribute 
that is applicable to the data or index component is specified 
for both the cluster and the component, the explicit component 
specification overrides that specified for the cluster. 

Note* A qualified data set name and an unqualified data set name 
cannot be placed in the same catalog if the first qualifier of 
the qualified name is the same as the unqualified name. For 
example, PAYROLL and PAYROLL. DATA cannot exist on the same 
catalog. 
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where ; 

yyddd is the date (year and Julian day) 

aaaaaaabbbbbbb is the timestamp value 

Refer to the chapter "Command Format" for a description of the 
command format for DEFINE CLUSTER. Examples of defining clusters 
are also included. 



SPECIFYING CLUSTER INFORMATION 



You specify all of the necessary descriptive information and the 
performance* security, and integrity options when you create a 
cluster. Some of the information you specify can apply to either 
the data or the index or to both. You can specify information 
for the cluster as a whole in the CLUSTER parameter. Information 
for data only or for index only goes with the corresponding 
parameter (DATA or INDEX). 

Descriptive Information 

Descriptive information includes^ 

Type of data organisation 

Whether the cluster is reusable (that is, for temporary 
storage of data) 

Average and maximum lengths of data records 

Length and position of the key field in the records of a 
key-sequenced data set 

Identity of • the catalog in which to define the cluster 

Identity of the volume(s) on which to allocate space for the 
cluster 

Amount of space to allocate for the cluster and whether the 
cluster is to reside in a separate data space 

Least amount of I/0-buffer space a processing program will 
provide to process the data set 

With a multivolume key-sequenced data set, you may assign data 
to the various volumes according to ranges of key values. For 
example: if you have three volumes you might assign records with 
keys A-E to the first volume, F-M to the second, and N-Z to the 
third. Key-range allocation* facilitates processing the data set 
with only one of the volumes mounted 5 you know which volume 
contains what records. All of the volumes specified for the, 
cluster's data component or for the index component must be of 
the same device type. However, the data component's device type 
can be different than the index component's device type. 

If a component is unique (that is, is to reside alone in a 
separate data space), the data space is not defined before the 
cluster is defined. The data space is created as the cluster is 
defined; in this case, the volume(s) must be mounted. 

If you don't specify the space to be provided for buffers, VSAM 
determines control interval size first and then sets 
buffei — space amount equal to the size of two data control 
intervals plus, for a key-sequenced data set, one index control 
interval. If you do specify it, data and index control intervals 
are limited to sizes such that the buffer space can hold two 
data control intervals and one index control interval. 

If the values you specify for record length and key length 
require control intervals too large for the buffer space you 
specify, the DEFINE command will fail. 
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The relationship between control interval size and least amount 
of I/0-buffer space is further discussed in OS/VS Virtual 
Storage Access Method (VSAM) Programmer's Guide . If you specify 
track allocation or specify record allocation for less than one 
cylinder, space is actually allocated by tracks. 

Performance Options Information 

Information for performance options (mostly for an indexed 
cluster) include: 

• Whether records can span control intervals 

• Whether to replicate index records 

• Whether to place the sequence set of an index adjacent to 
data 

• Whether to place the cluster's index on a separate volume 
from data 

• The amount of free space to remain in the data component's 
control intervals and control areas when the data records 
are loaded (applies only to a key-sequenced cluster's data 
component) 

• Control interval size for VSAM to use instead of calculating 
the size itself 

These options are discussed in OS/VS Virtual Storage Access 
Method (VSAM) Programmer's Guide . 

In a system with the Mass Storage System, you can also indicate 
how a cluster or component that is stored on a mass-storage 
volume is to be staged. 

Protection and Integrity Information 

Information for protection and integrity options include 1 

• Passwords and related information 

• Identity of your own authorization routine to verify that a 
requester has the right to gain access to data 

• Identity of an I/O erroi — handling routine (the exception 
exit routine) that is branched to before the program's SYNAD 
exit is taken 

• Whether to Preformat control areas during data record 
i nserti on 

• Whether to verify that write operations are without error 

• Whether and to what extent to share data among systems, 
jobs, and subtasks 

• Whether to erase the information that a data set contains 
when you delete the data set 

These options are discussed in the chapter "Data Security and 
Protection" and in Planning for Enhanced VSAM Under OS/VS . 

In a system with the Mass Storage System, you can also indicate 
whether a cluster or component that is stored on a mass storage 
volume is to be destaged synchronously or asynchronously with 
respect to the program that closes it. 
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DEFINING AN ALTERNATE INDEX 



An alternate index can*be defined over a key-sequenced cluster 
or over an entry-sequenced cluster. An alternate index cannot be 
defined to support a reusable cluster, a relative-record 
cluster, a catalog, another alternate index, or a nonVSAM data 

set. ' 

Before you can build an alternate index, you must define and 
load its base cluster (see the DEFINE CLUSTER command), then 
define the alternate index and relate it to the base cluster. 
The base cluster and alternate index are described by entries in 
the same catalog. 

You can issue the DEFINE ALTERNATEINDEX command to define an 
alternate-index entry and allocate space for an alternate index. 
VSAM uses more than one catalog entry to describe the alternate 
index (an alternate index is conceptually a key-sequenced 
cluster) : 

• An alternate-index entry describes the alternate index as a 
key-sequenced cluster. 

• A data entry describes the alternate index T s data component. 

• An index entry describes the alternate index's index 
component. 

Attributes of the alternate index's components can be specified 
separately from the attributes of the alternate index. When 
attributes are specified for the alternate index as a whole and 
are not specified for the components, the attributes of the 
alternate index (except for its passwords and other protection 
attributes) are propagated to the alternate index's components. 
The attribute specified for the component overrides that 
specified for the alternate index. 

When you define the alternate index, you identify it with an 
entryname. The entryname identifies the alternate index when it 
is described with a JCL DD statement (that is, the entryname is 
the JCL DD statement's dsname) and when it i s processed with 
another Access Method Services command. You can also name the 
alternate index's components; a user's program can open and 
process the alternate index's data or index component as a data 
set. For example, your program can open the index of an 
alternate index, then read and write its records. For more 
details on this kind of processing, see OS/VS Virtual Storage 
Access Method (VSAM) Options for Advanced Applications . 

Refer to the chapter "Command Format" for a description of the 
command format for DEFINE ALTERNATEINDEX. An example of defining 
an alternate index is also included. 



SPECIFYING ALTERNATE-INDEX INFORMATION 



When you define an alternate index, you specify descriptive 
information and performance, security, and data-integrity 
options. Some of the information you specify can apply to either 
the alternate index's data component, or to its index component, 
or to both — that is, to the alternate index as a whole. You 
specify information for the alternate index as a whole with the 
ALTERNATEINDEX parameter and its subparameters. Information for 
the data component or for the index component is specified with 
parameters of DATA or INDEX. 
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Descriptive Information 



Information that you specify to describe the alternate index 
being defined includes: 

• The base cluster related t^ the alternate index. 

• Whether the alternate index is reusable (that is, 
temporary) . 

• Average and maximum lengths of alternate-index records. 

• Length and position of the key field in data records of the 
alternate index's base cluster. 

• Identity of the catalog that is to contain the alternate 
index's entries (the same catalog that contains the base 
cluster's entries). 

• Identity of the volume(s) on which space is to be allocated 
for the alternate index. 

• Amount of space to allocate for the alternate index and 
whether the alternate index is to reside in a separate data 
space. 

• The least amount of I/O buffer space that a user's program 
is to provide when the program processes the alternate 
index's data. 

You can define an alternate index with its records assigned to 
various volumes according to alternate-key value. Each volume 
can contain the alternate-index records whose alternate key 
values are between a low-key value and a high-key value — that 
is, records whose alternate-key values are within a key range. 
For example, your alternate index might reside on three volumes. 
The records with alternate keys A through E are on the first 
volume, F through M on the second volume, and N through Z on the 
third volume. 



Performance Options Information 



Information that you can specify to improve the performance of 
your alternate index include 1 

• Control-interval size, instead of allowing VSAM to calculate 
an optimum sise. 

• Whether to place the index's sequence set adjacent to the 
data control areas. 

• Whether to place the alternate index's index on a separate 
volume (or direct-access device) from the alternate-index 
records. 

• The amount of free space to remain in the data component's 
control intervals and control areas when the alternate-index 
records are loaded (applies only to the alternate index's 
data component). 

These options are discussed in OS/VS Virtual Storage Access 
Method (VSAM) Programmer's Guide . 

In a system with the Mass Storage System, you can also indicate 
how an alternate index or component that is stored on a 
mass-storage volume is to be staged. 
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Protection and Integrity Information 



Information that you can specify to protect your alternate 
index's records from other users and from possible system errors 
include: 

• Passwords and related usei — verification information. 

• Identity of your authorization routine to verify that a 
user's program is authorized to gain access to the alternate 
index's records. 

• Identity of your I/O erroi — handling routine (the exception 
exit routine) that is branched to before the program's SYNAD 
exi t is taken. 

• Whether to Preformat control areas before the 
alternate-index records are loaded. 

• Whether, and to what extent, to share your alternate index 
between subtasks, jobs, and systems. 

• Whether to erase the information that your alternate index 
contains when you delete it. 

These options are discussed in "Data Security and Protection" 
and in Planning for Enhanced VSAM Under OS/VS . 

In a system with the Mass Storage System, you can also indicate 
whether an alternate index or component that is stored on a 
mass-storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 



DEFINING A PATH 



The DEFINE PATH command is used to establish the relationship, 
the path, between an alternate index and its base cluster. The 
base cluster and its alternate index must already be defined 
when you define the path that relates them. 

When your program opens a path for processing, both the 
alternate index and its base cluster are opened. When data in 
the base cluster is read or written using the path's alternate 
index, keyed processing is used; RBA processing is not allowed. 

You can also use the DEFINE PATH command to establish a 
password-protected alias for a VSAM cluster. The cluster must 
already be defined when you define a path as its alias. The path 
entry, as an alias, allows the cluster another set of protection 
attributes. You. can specify NOUPDATE access for the cluster, 
which allows you to open the cluster without also opening its 
upgrade set (that is, all of the cluster's alternate indexes 
that are to be updated whenever the cluster's data i s changed). 

Refer to the chapter "Command Format" for a description of the 
command format for the DEFINE PATH command. An example for 
defining a path is also included. 



DEFINING A NONVSAM DATA SET 



The DEFINE command can be used to catalog a nonVSAM data set in 
a VSAM catalog. Any already existing nonVSAM data set can be 
introduced into a master or user catalog through the DEFINE 
command. The result of a DEFINE command when it i s used to 
define a nonVSAM entry i s that an entry is created in a master 
or user catalog; no space is allocated or reserved. 
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When you define* alter* or delete a nonVSAM data set in a 
password-protected catalog, the catalog's update- or 
highei — level password is required. 

Refer to the chapter "Command Format" for a description of the 
command format and an example of the DEFINE NONVSAM command. 



DEFINING AN ALTERNATE NAME 

The DEFINE command can be used to define an alternate name — an 
alias — for a nonVSAM data set (even if it is a generation data 
set). DEFINE ALIAS can also be used to define an alias for a 
user catalog connector in the master catalog. An alias cannot, 
however, be defined for a generation data group. 

Refer to the chapter "Command Format" for a description of the 
command format for DEFINE ALIAS. An example is also included. 

HOW TO USE AN ALIAS TO IDENTIFY A USER CATALOG 

When you define an alias for a usei — catalog connector, you 
should structure the alias so that the catalog's cataloged data 
sets can be located when the alias is used. If VSAM is 
searching 1 for a usei — specified entryname (that identifies a 
data set) and does not find its entry in the master catalog or a 
user catalog identified with the JOBCAT or STEPCAT DD 
statements, and if the entryname's catalog is not specified, 
VSAM assumes that* 

• The entry resides in a user catalog, and 

• The usei — catalog's name or alias is the first simple name of 
the qualified entryname. 

If the entryname is ABC. DE. DATA, VSAM searches the master 
catalog for a usei — catalog connector entry (that is, an entry 
with the name or alias of ABC). If found, VSAM next searches 
catalog ABC for an entry identified by the name or alias 
ABC. DE. DATA. 

If you identify a catalog with a name of ABC.DE and catalog the 
entry whose name is ABC.DE. DATA in that catalog, the catalog 
won't be found when VSAM searches for it. In order for VSAM to 
find the entryname ABC.DE. DATA (an entry in the catalog whose 
name is ABC.DE), the catalog's name, ABC.DE, must also be 
specified (either explicitly in the Access Method Services 
command that refers to data set ABC.DE. DATA, or as a JOBCAT or 
STEPCAT DD statement). 

You can delete the alias of a user catalog and redefine it in 
the same step, but you cannot use it in that step. A TSO session 
is considered one step, so you would have to log off and log on 
to use an alias of a user catalog that you had deleted and 
redefined. 



For a detailed description of, and the correct search sequence for, how 
VSAM searches catalogs to locate an entry, see the section "Order of 
Catalog Use" for the various commands. 
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DEFINING A GENERATION DATA GROUP 



The DEFINE command can be used to create a catalog entry for a 
generation data group. For further information on generation 
data groups, see QS/VS2 MVS Data Management Services Guide . 

Once a catalog entry for a generation data group has been 
created, existing data sets can be attached to it as generation 
data sets. This is accomplished through JCL, in the form 
DSNAME = name(n) (where n is the generation increment) , or by 
defining each data set as a nonVSAM data set with a generation 
data set name, as follows* 

name. GnnnnVnn 

If the name is found to match the name of a previously defined 
generation data group, the nonVSAM data set is associated with 
the generation data group as a generation data set. See 
"Defining a NonVSAM Data Set" for a description of how to define 
a nonVSAM entry. 

When you create a generation data group it can be cataloged in a 
VSAM catalog. The model DSCB must exist on the generation data 
group's catalog volume. To create a generation data group in an 
OS CVOL, you can use the BLDG function of the OS/VS utility, 
IEHPROGM. All JCL specifications available to support generation 
data groups work on VS2 Release 2 and later releases in a way 
equivalent to OS/MVT, VS2 Release 1, or VS2 Release 1.6, whether 
the generation data group is cataloged in a VSAM catalog or in 
an OS CVOL. 

Refer to the chapter "Command Format" for a description of the 
command format for DEFINE GENERATIONDATAGROUP . An example is 
also included. 



DEFINING A PAGE SPACE 



The DEFINE command can be used to define an entry for a page 
space. A page space is an 0S/VS2 system data set that contains 
pages of virtual storage; the pages are stored into and 
retrieved from the page space by the Auxiliary Storage Manager. 
A page space is a non indexed data set (that is, an 
entry-sequenced cluster) that is entirely Preformatted before it 
is used. In a system with the Mass Storage System, a page space 
cannot be defined on a mass-storage volume. A page space must 
reside on a single volume. A page space cannot be opened as a 
user data set. 

A page space has a maximum usable size equal to 65,535 paging 
slots (records). See the description for space size declarations 
(CYLINDERS, RECORDS, and TRACKS for DEFINE PAGESPACE) in the 
"Command Format" chapter for further details. 

You can define a page space in a user catalog, then move the 
catalog to a new system and establish it as the system's master 
catalog. When you define a page space in a user catalog, you 
must also code a STEPCAT or JOBCAT statement to identify and 
allocate the catalog. 

When you issue a DEFINE PAGESPACE command, the system creates an 
entry in the catalog for the page space, and then Preformats the 
page space. If an error occurs during the Preformatting process 
(for example, an I/O error or an allocation error), the 
page-space entry in the catalog exists even though no space for 
it exists. You must issue a DELETE command to remove the 
page-space entry before you redefine the page space. 

Each page space is represented by two entries in the catalog* a 
cluster entry and a data entry (that is, a page space is 
conceptually an entry-sequenced cluster.) Both of these entries 
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shftuld be password protected if the page space is to be password 
protected. (Note: The passwords you specify with the DEFINE 
PAGESPACE command are put in both the page space's cluster entry 
and its data entry.) When you define page spaces during system 
generation (SYSGEN), you should use the ALTER command to add 
passwords to each entry, since passwords cannot be specified 
during system generation. 

In addition, you should ensure that the catalog containing the 
page-space entry is password protected. Otherwise, a user can 
list the catalog's contents and find out each entry's passwords. 

A page space i s made known to the system as a system data set at 
system-generation time or through members of a partitioned data 
set* SYS1 .PARMLIB . To be used as a page space, a page space must 
have been defined in a catalog that is currently being used as 
the master catalog (that is, a page space cannot be used if its 
entry is in a user catalog). 

A page space's passwords and protection attributes are cataloged 
in both the page-space entry and its data-component entry. You 
should specify master, control, update, and read passwords to 
prevent the page space from being accessed if its volume is 
moved to a VS1 system. The VS2 system automatically prevents a 
user's program from accessing a page space or its data 
component. 

Refer to the chapter "Command Format" for a description of the 
command format of DEFINE PAGESPACE. Examples of how to define 
page spaces are also included. 
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BUILDING AN ALTERNATE INDEX 



The BLDINDEX command is used to build an alternate index. Before 
you can build an alternate index, you must define and load its 
base cluster (see the DEFINE CLUSTER command), then define the 
alternate index and relate it to the base cluster (see the 
DEFINE ALTERNATEINDEX command). The base cluster and alternate 
index are described by entries in the same catalog. 

The alternate index's volume and the base cluster's volume must 
be mounted during the build process. Any volumes identified with 
the WORKFILES parameter must also be mounted. 

An alternate index can be built for a key-sequenced cluster or 
for an entry-sequenced cluster. The base cluster must be 
nonempty (that is, its high-used RBA value cannot be zero). An 
alternate index cannot be built to support an empty or reusable 
cluster, a relative-record cluster, a catalog, another alternate 
index, or a nonVSAM data set. 

Each of the base cluster's data records must be long enough to 

contain the alternate key. Each record's alternate-key value 

must be unique, unless the alternate index was defined with the 
NONUNIQUEKEY attribute. 

Refer to the chapter "Command Format" for a description of the 
command format for BLDINDEX. Examples of the BLDINDEX command 
are also included. 



HOW AN ALTERNATE INDEX IS BUILT 



When an alternate index is built by BLDINDEX processing, Access 
Method Services opens the base cluster to sequentially read the 
data records, sorts the information obtained from the data 
records, and builds the alternate-index records 1 

1. The base cluster is opened for read-only processing. You can 
prevent other users from updating the base cluster's records 
during BLDINDEX processing by including the DISP=0LD 
parameter in the base cluster's DD statement. If INDATASET 
is specified, Access Method Services will dynamically 
allocate the base cluster with DISP=0LD. 

2. The base cluster's data records are read and certain 
information is extracted to form the key-pointer pair: 

• When the base cluster is entry-sequenced, the 
alternate-key value and the data-record's RBA form the 
key-pointer pair. 

• When the base cluster is key-sequenced, the 
alternate-key value and the data-record's prime-key 
value form the key-pointer pair. 

If the base cluster's data records can span control 
intervals, the alternate key must be in the record's first 
segment (that is, the first control interval). 

3. The key-pointer pairs are sorted in ascending alternate-key 
order. If your program provides enough virtual storage, 
Access Method Services performs an internal sort (that is, 
the sorting of key-pointer pairs takes place entirely within 
main, or virtual, storage). 

You can determine the amount of virtual storage required to 
sort the records internally by using the following process: 
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a. Sort record length = alternate key length + (prime key 
length (for a key-sequenced data set) or 4 (for an 
entry-sequenced data set)). 

b. Record sort area size = sort record length x number of 
records in base cluster, rounded up to the next integer 
multiple of 2048, or 32,768, whichever is greater. 

This means the record sort area size will be a minimum 
of 32,768, or sort record length x number of records 
rounded up to the next 2K boundary. 

c. Sort table size = (record sort are& size -f- sort record 
length) x 4. 

The sum of b and c above is the required amount of virtual 
storage for an internal sort. This amount is in addition to 
the normal storage requirements for processing an Access 
Method Services command. 

If you do not provide enough virtual storage for an internal 
sort, or when you specify the EXTERNALSORT parameter, Access 
Method Services defines and uses two sort workf i les and 
sorts the key-pointer pairs externally. Access Method 
Services uses the sort workf i les to contain most of the 
key-pointer pairs while it sorts some of them in virtual 
storage. This process is called an external sort. An 
external-sort workf i le is a VSAM entry-sequenced cluster, 
marked reusable, with space suballocated from a VSAM data 
space. The minimum amount of virtual storage you will need 
for an external sort is : 

32,768 + ((32,768 H- sort record length) x 4) 

The amount of space that Access Method Services requests 
when defining each sort workf i le is calculated as follows* 

a. Sort records per block = 2041 sort record length 

b. Primary space allocation in records = 

(number of records in base cluster sort records per 
block) + 10 

c. Secondary space allocation in records = 

(Primary space allocation x 0.10) + 10 

Both primary and secondary space allocation ar& requested in 
records with a fixed-length record size of 2041 bytes and a 
control interval size of 2408 bytes. 

4. When the key-pointer pairs have been sorted into ascending 
alternate-key order, Access Method Services builds an 
alternate-index record for each key-pointer pair. If the 
alternate index is defined with the NQNUNIQUEKEY attribute 
and more than one key-pointer pair have the same 
alternate-key values, the alternate-index record that is 
built contains the alternate-key value followed by the 
pointer values in ascending order. If the alternate index is 
defined with the UNIQUEKEY attribute, each alternate-key 
value is uni que. 

When the record is built, it is written into the alternate 
index as though it is a data record being loaded into a 
key-sequenced cluster. Attributes and values that apply to 
the loading of data records can be specified when the 
alternate index is defined and are- RECORDSIZE, 
CONTROLINTERVALSIZE, BUFFERSPACE, FREESPACE, WRITECHECK, 
SPEED, RECOVERY, REPLICATE, and IMBED. 

5. When all alternate-index records have been built and loaded 
into the alternate index, both it and its base cluster are 
closed. Steps 1 through 4 are repeated for each alternate 
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index that is specified with the OUTFILE or OUTDATASET 
parameter. When all alternate indexes have been built, if 
external sort workfi les have been defined, they are deleted. 
Access Method Services finishes processing and issues 
messages that indicate the results of the processing. 

DD STATEMENTS THAT DESCRIBE THE SORT WORKFILES 

You can identify VSAM data space that the sort routine can use 
by specifying two dnames with the WORKFILES parameter and 
supplying two DD statements that describe the workfi les to b__ 
defined by Access Method Services. Each workfile DD statement 
should be coded 1 

//ddname DD D5NAME=dsname, VOL=SER=volser, 
// UNIT=devtype,DISP=OLD,AMP= , AMORG' 

ddname 

As specified in the WORKFILES parameter. If you do not 
specify the WORKFILES parameter and you intend to provide 
VSAM data space for external-sort workfi les, you identify 
the workfile DD statements with the names IDCUT1 and 
IDCUT2. 

dsname 

A data set name. The OS/VS Scheduler generates a data set 
name for the workfile if none is provided. 

VOL=SER=volser 

Required. Identifies the volume owned by the STEPCAT, 
JOBCAT, or master catalog in which the workfile is to be 
cataloged. The workfi le's space is suballocated from the 
volume's VSAM data space. You can specify a maximum of five 
volumes for each workfile. See the section "How an 
Alternate Index is Built" for a description of how to 
calculate the amount of space to be suballocated for each 
sort workfile. If your BLDINDEX job requires external-sort 
workfi les, this space must be available on the volume(s) 
identified by volser or your job will fail, 

UNIT=devtype 

Type of direct-access device on which the volume is 
mounted. You can specify a generic device type (that is, 
3330, 2314, etc.) or a unit address (that is, 121, 248, 
etc.). You cannot specify SYSDA. 

DISP=OLD 

Required. 

AMP= , AMORG' 

Required. 

If BLDINDEX is being used interactively in a TSO environment, 
these sort workfile DD statements must be contained in a logon 
procedure. 



ORDER OF CATALOG USE: BLDINDEX 



The base cluster and alternate-index entries are in the same 
catalog, because the catalog owns the volume or volumes that 
contains the cluster and its alternate index. 

The order in which catalogs are selected to determine the 
catalog to contain the external-sort workfile entries (that is, 
entries that describe each workfile as an entry-sequenced 
cluster in a suballocated VSAM data space) is* 

1. If a catalog is specified with the CATALOG parameter, that 
catalog is selected to contain workfile entries. Otherwise, 
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2. The user catalog specified in the current job step (STEPCAT) 
or, if none is specified for the job step, the user catalog 
specified for the current job (JOBCAT) is selected to 
contain the workfile entries. If more than one catalog is 
specified for the job step or job, the first job step or job 
catalog is selected to contain the workfile entries. 
Otherwi se, 

3. If the entries (data set name on the DD statement) are 
identified with qualified entrynames and the first qualifier 
is the same as: 

• the name of a user catalog, or 

• the alias of a user catalog, 

the user catalog so identified is selected to contain the 
workfile entries. Otherwise, 

4. The master catalog is selected to contain the workfile 
entri es. 
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MODIFYING CATALOG INFORMATION 



The ALTER command is used to alter attributes in catalog entries 
and to rename members of nonVSAM partitioned data sets. To alter 
an entry* you need to supply its name and the attributes to be 
altered. 

Altering an entry does not normally require that the entry's 
volume be mounted, because the entry's use of space and the 
availability of space in the volume's data spaces can be 
determined by examining the catalog. The entry's volume must be 
mounted whenever the volume's VTOC must be consulted or 
modified, such as when a unique component or nonVSAM data set is 
renamed. The entry's volume must also be mounted when the entry 
is cataloged in a recoverable catalog. A JCL DD statement can be 
used to cause the data set or volume to be allocated. In 0S/VS2 
MVS, a data set or volume can be dynamically allocated by 
specifying the data-set name or volume serial number if no DD 
statement is supplied. The volume must be mounted as permanently 
resident or reserved. 

Key-sequenced VSAM data sets consist of three components 1 an 
index component, a data component, and the cluster entry itself. 
Most attributes of the VSAM data set are associated with its 
data or index components. Certain attributes such as retention 
period, owner ID, and cluster protect i on are associated with the 
cluster entry itself. If you use the cluster name in the ALTER 
command, only these attributes will be changed. If you use the 
cluster name in the ALTER command to alter any attribute not 
di rectly associ ated wi th the cluster entry, Access Method 
Services will terminate the ALTER request and issue an error 
message. The converse is also true; if you specify a data or 
index component name and attempt to alter an attribute directly 
associated with a cluster entry, Access Method Services will 
terminate your ALTER command and issue an error message. You 
must specify the explicit data or index component name in order 
to alter any of the remaining attributes such as shareopt i ons, 
bufferspace, writecheck, the data or index protection 
attributes, etc. It is recommended, therefore, that you specify 
data and index component names at DEFINE time in order to 
facilitate the use of the ALTER command. Otherwise, you will 
have to use the long system-generated names. Refer to Figure 8 
in the chapter "Command Format" to determine which values or 
attributes you may alter for a particular entry type. 

You cannot ALTER any attributes of a user catalog except those 
directly associated with the cluster name. Data and index 
component names specified for a user catalog at DEFINE time are 
meaningless, because the system will always generate standard 
names. If you specify these system-generated names for the data 
or index components in the ALTER command, VSAM will return a 
catalog return code of "8," claiming the entry is not there. 
Additionally, if you alter the expiration date to an invalid 
date, such as "99999," Access Method Services will return a 
condition code of "0" even though the expiration date remains 
unchanged. 

Refer to the chapter "Command Format" for a description of the 
command format for ALTER. Examples of the ALTER command are also 
i ncluded. 
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ORDER OF CATALOG USE: ALTER 



The order in which catalogs are searched when an entry is to be 
located to be altered is : 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found* a "no 
entry found" error is returned to the user. 

2. Any user catalog(s) specified in the current job step (with 
a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. 

If a STEPCAT catalog is specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 

If no STEPCAT catalog is specified for the job step, and a 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname and 
its first qualifier is the same as : 

• the name of a user catalog, or 

• the alias of a user catalog, or 

• the alias of a control volume, 

the user catalog or control volume so identified is 
searched. If the entry is found, no other catalog is 
searched. Otherwise, 

4. The master catalog is searched. If the entry is not found, a 
"no entry found" error is returned to the user. 



GENERIC NAMES AND ALTER 



To alter entries with qualified names — for example, 

PAYROLL . 74 .MAY — you can identify the entry with its full name 

(that is, all qualifiers) or with all qualifiers but one. The 

unspecified qualifier is indicated with an asterisk (for 

example, PAYROLL . * .MAY) . This kind of shortened name, 

PAYROLL . * .MAY, is called a generic name. When you specify the 

full entryname, only the entry so identified is modified. When 

you specify all qualifiers of the entryname but one, the entries 

whose entrynames match the supplied qualifiers are altered, if 

they contain the type of information specified with the ALTER 

command's parameters. 

For example, when you specify PAYROLL.*, the entries that might 

be altered are those whose entrynames contain two qualifiers, 

the first qualifier being PAYROLL. When you specify 

PAYROLL .* .MAY, the entries that might be altered are those whose 

entrynames contain three qualifiers, the first being PAYROLL and 

the third and last being MAY. 
% 

When you identify a catalog (that is, when you specify the ALTER 
command's CATALOG parameter), Access Method Services searches 
only the specified catalog for generically named entries. If no 
catalog is specified, the catalog is selected as indicated in 
"Order of Catalog Use: ALTER" and is searched for generic-named 
entri es. 

You must always specify the first qualifier of a qualified 
entryname. You can substitute an asterisk for no more than one 
of the other qualifiers. 
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You must identify all qualifiers in the qualified name. For 
example, PAYROLL.* cannot be used to identify a qualified name 
that contains three or more qualifiers, even though its first 
qualifier is PAYROLL. PAYROLL .74 .MAY.* cannot be used to 
identify a qualified name that has more or fewer than four 
qual i f i ers. 



Renaming Generically-Named Entries 



You can use generic names to rename a group of cataloged 
objects. To do this, you specify both the entryname and the new 
name as generic names. For example, if each entryname identified 
with the generic name A.*.B is to be renamed with the generic 
name A.K.C, all entrynames that have A as the first qualifier 
and B as the third and last qualifier are renamed. The new name 
has A as the first qualifier and C as the third and last 
qual i f i er J 

Old Name New Name 

A.l.B A.l.C 

A.2.B A.2.C 

A.3.B A.3.C 

If each entryname identified with the generic name A.B.H.D is to 
be renamed, all entrynames that have A and B as the first and 
second qualifiers, and D as the fourth and last qualifier, are 
renamed. If the new generic name is C.H.DATA, the entry names 
are renamed as follows* 

Old Name New Name 

A.B.l.D C.l.DATA 

A.B.2.D C. 2. DATA 

A.B.3.D C. 3. DATA 



VSAM VOLUME RECOVERY FUNCTION 



The VSAM Volume Recovery function removes all VSAM data spaces 
and resets volume ownership for a volume that cannot be located 
with its catalog entry (that is, a system failure or I/O error 
might have damaged the volume entry). The volume's format-4 DSCB 
(in the VTOC) is reset to remote its ownership from the VSAM 
catalog. NonVSAM data sets on the volume are not affected. The 
VSAM catalog that owns the volume is not accessed or 
modified — the (damaged) volume entry is unchanged. 

The VSAM Volume-Recovery function can be used to remove a user 
catalog from a volume without first deleting each of the 
catalog's objects (that is, VSAM objects and nonVSAM data sets 
described with the catalog's entries). The VSAM Volume-Recovery 
function allows you to remove a VSAM user catalog that has been 
damaged by a head crash, a standalone DASDI, or a similar 
acci dent. 

VSAM erases all VSAM data spaces (even when they contain data or 
a catalog) and rewrites the volume's VTOC to indicate additional 
free space on the volume. You should use this function only when 
yo'u cannot access the catalog that owns the volume. You should 
use the function carefully, in order to prevent unwanted loss of 
data. When improperly used, this function can contribute to 
system integrity exposures. See the section "VSAM Volume 
Cleanup" in the chapter "Data Security and Protection" for 
further information about the volume-recovery function. 
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When you use the ALTER command to recover from a damaged volume, 
you code the command in this format 5 

ALTER entryt/password] 
FILE(dname) 
REMOVEVOLUMES(volserCb volser...]) 

entrynameC/password 3 

names the master catalog. If the master catalog is password 
protected, then its master password must also be supplied. 

FILE(dname) 

specifies the name of a DD statement that describes a 
volume to be reset. If more than one volume is to be reset, 
they must be of the same device type. Concatenated DD 
statements are not allowed. This parameter is required. 

REMOVEVOLUMEStvolserCb volser...]) 

identifies the volume(s) on which all VSAM data spaces are 
to be removed. VSAM ownership of the volume is also 
relinquished. Volumes owned by the master catalog 
identified in entryname cannot be specified. 
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DISPLAYING CATALOG INFORMATION 



The LISTCAT command is used to list entries from a catalog. The 
entries listed can be selected by name or entry type, and the 
fields to be listed for each entry can additionally be selected. 
See "Appendix B. Interpreting LISTCAT Output" for an explanation 
of the output produced as a result of the LISTCAT command. 

If entries to be listed are selected by name, the name(s) can be 
specified in its entirety, can be specified as a generic name, 
or can be specified with the LEVEL parameter. 

Entries are specified by generic name by supplying all but one 
qualifier of the name. The qualifier omitted is indicated by an 
asterisk (*). The first qualifier cannot be omitted. 

When you specify ENTRIES (A.*), all two-qual i f i.er entrynames 
that have A for the first qualifier are selected to be listed. 
When you specify ENTRIESC A .* , B) , all three-qualifier entrynames 
that have A as the first qualifier and B as the last qualifier 
are selected to be listed. You can further limit the printing by 
identifying certain entry types to be printed (that is, by 
specifying NQNVSAM, CLUSTER, etc.). 

When you specify LEVEL( A . * . B) , all entrynames that have A as the 
first qualifier and B as the third qualifier are selected to be 
listed — and some of the selected entrynames might have four or 
more qualifiers (each must have at least three qualifiers and 
satisfy the A.*.B selection criteria). 

When you specify LEVEL(A), all entrynames that have A as the 
first qualifier (regardless of the number of qualifiers) are 
selected to be listed. 

You cannot specify an "*" as the last qualifier when you use the 
LEVEL parameter (note that when you specify LEVEL(A), more 
entries might be listed than when you specify ENTRIES( A . *) , even 
though both ways appear, at first glance, to be identical). If 
you specify LEVEL(A.H), the LISTCAT operation terminates with an 
error message. 

Restriction for use of REPRO and LISTCAT in same job step: 
LISTCAT cannot run in a job step where the catalog is empty when 
it is opened. To ensure that the LISTCAT correctly reflects the 
contents of the catalog, it is recommended that LISTCAT be run 
as a separate job step. 

Refer to the chapter "Command Format" for a description of the 
command format for LISTCAT. Examples are also included. 



ORDER OF CATALOG USE: LISTCAT 



When the ENTRIES or LEVEL parameter is not specified, or when 
the command is not executed through TSO, the order in which 
catalogs are searched when entries are to be listed using the 
LISTCAT command is : 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is listed. Otherwise, 

2. The first user catalog specified in the current job step 
(STEPCAT) or, if none is specified, the first user catalog 
specified in the current job (JOBCAT) is listed. Otherwise, 

3. If no user catalog is specified in the current job step or 
job, the master catalog is listed. 
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When the ENTRIES or LEVEL parameter is specified, or when the 
command is executed through TSO, the order in which catalogs are 
searched when entries are to be listed using the LISTCAT command 
i 5! 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found" error is returned to the user. Otherwise, 

2. Any user catalog(s) specified in the current job step 
(STEPCAT) or, if none is specified for the job step, any 
user catalog(s) specified for the current job CJOBCAT). If 
more than one catalog is specified for the job step or job, 
the job step or job catalogs are searched in order of 
concatenation. If the entry is found, no other catalog is 
searched. Otherwise, 

3. If the entry is not found, and the entry's name is a 
qualified name, and the first qualifier (that is, the first 
one to eight characters before a period) is the same as 5 

• the name of a user catalog, or 

• the alias of a user catalog, or 

• the alias of a control volume, 

that user catalog or control volume is searched. If the 
entry is found, no other catalog is searched. Otherwise, 

4. The master catalog is searched. If the entry is not found, a 
"no entry found" error is returned to the user. 
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DELETING CATALOG ENTRIES 



The DELETE command is used to delete entries from a catalog or 
to delete members of a nonVSAM partitioned data set. When the 
entry represents an object that contains space in a VSAM data 
space, the object's space is made available for other VSAM 
objects. 

Deleting an entry does not normally require that the entry's 
volume be mounted, because the entry's use of space in the 
volume's data spaces can be determined by examining the catalog. 
The entry's volume must be mounted whenever the volume's VTOC 
must be consulted or modified, such as when : 

• A data space, a unique component, or a user catalog i s to be 
deleted. 

• A cluster or alternate index is to be deleted and erased. 

• A nonVSAM data set is to be deleted and scratched. 

If the entry is cataloged in a recoverable catalog, its prime 
catalog recovery area volume must be mounted so that the CRA can 
be updated to reflect the entry's deletion. 

For multi volume VSAM data sets, each volume must be mounted to 
reflect the entry's deletion from the volume's catalog entry. 
See "Restoring Catalog Entries After System Failure" for a 
description of catalog recovery area contents. 

JCL can be used to cause a data set or volume to be allocated. A 
data set or volume can be dynamically allocated by specifying 
the data set name or volume serial number if no DD statement is 
supplied. Any volume to be dynamically allocated must be mounted 
as permanently resident or reserved. 

Entries can be deleted from more than one catalog with a single 
DELETE command. You do this by specifying many entry names and 
not coding the CATALOG parameter. Use concatenated JOBCAT or 
STEPCAT DD statements to identify the catalogs that contain the 
entri es. 

Note: When two catalogs in your system might contain the same 
entryname, you should issue separate DELEJE commands that 
reference each catalog. 

The kinds of catalog entries you can delete are'- 

• ALIAS- — The alias entry is deleted. 

You can delete the alias of a user catalog and redefine 
it in the same step, but you cannot use it in that step. 
A TSO session is considered one step so you would have 
to log off and log on to use an alias of a user catalog 
that you had deleted and redefined. 

Password required: the catalog's update- (or 
highei — level) password. 

• ALTERNATEINDEX — The alternate-index entry, its data 
component's entry, and its index component's entry are 
deleted. Space allocated to the alternate index's components 
is made available for other VSAM objects. Each path entry 
that relates the alternate index to its base cluster is also 
deleted. 

When ERASE is coded, or when the alternate index has the 
ERASE attribute, the volume containing the alternate 
index's data component must be mounted. 
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The alternate index's components cannot be deleted 
separately. You must delete the alternate index as a 
whole. When the alternate index's components reside in 
unique data spaces, the volumes containing these 
components must be mounted. 

If the alternate index is cataloged in a recoverable 
catalog* the prime catalog recovery area volume as well 
as other volumes for the alternate index must be 
mounted. The prime volume is the first index volume of 
the base cluster over which the alternate index is 
defined if the cluster is a KSDS. Otherwise, it is the 
data volume of the cluster. Its volume serial number is 
printed by Access Method Services when the alternate 
i ndex i s def i ned. 

Password required? the alternate index's master password 
or its catalog's master password. 

CLUSTER — The cluster entry, its data component's entry, and, 
if the cluster is key-sequenced, its index component's entry 
are deleted. Space allocated to the cluster's components is 
made available to other VSAM components. 

Alternate indexes that are associated with the cluster 
are deleted. The cluster's upgrade-set entry, if it 
exists, is also deleted. Path entries that relate the 
cluster*to its alternate indexes are also deleted, as 
well as path entries that have been defined for the 
cluster alone. 

Space allocated to the alternate index's components is 
made available to other VSAM objects. When the alternate 
index's components reside in unique data spaces, the 
volumes containing these components must be mounted. 

When ERASE is coded, or when the cluster has the ERASE 
attribute, the volume containing the cluster's data 
component must be mounted. 

The cluster's components cannot be deleted separately. 
You must delete the cluster as a whole. When the 
cluster's components reside in unique data spaces, the 
volumes containing these components must be mounted; 
then data spaces are automatically deleted. 

When the cluster is cataloged in a recoverable catalog, 
the prime catalog recovery area of the volume as well as 
all other volumes of the cluster must be mounted. The 
prime volume is the first volume containing the index 
component of the cluster if the cluster is a KSDS. 
Otherwise, it is the first data volume of the cluster. 
Its volume serial number is printed by Access Method 
Services when the cluster is defined. 

Password required? the cluster's master password or its 
catalog's master password. 

GENERATIONDATAGROUP — The generation data group (GDG) entry 
is deleted. The generation data group must be empty (that 
is, it cannot contain generation data sets) unless you 
specify FORCE. 

Password required? the catalog's update- (or 
highei — level) password. 

Note? On MSS volumes, a GDG data set may not be scratched 
when it is automatically uncataloged, even if the SCRATCH 
option has been specified. 

MASTERCATALOG — In a VS2 system, the VSAM master catalog is 
the system's primary catalog. You are not allowed to delete 
your system's master catalog. 
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• NONVSAM — The nonVSAM entry is deleted. When SCRATCH is 
coded, the data-set's DSCB is removed from its volume's 
VTOC — the volume containing the nonVSAM data set must be 
mounted. 

All alias entries that point to the nonVSAM entry are 
also deleted. 

When the nonVSAM data set is partitioned, you can delete 
one of its members by specifying the entryname as 

pdsnameC member name) 

Password requi red : the catalog's update- (or 
highei — level) password. 

• PAGESPACE — The page-space entry and its data-component entry 
are deleted. Space allocated to the page-space is made 
available to other VSAM objects. 

The page space being deleted must be inactive when it is 
deleted, and all other page spaces on the same volume 
must also be inactive. 

Password requi red-* The page space's master password or 
the catalog's master password. 

• PATH — The path entry is deleted. Entries for the path's 
alternate index and base cluster are undisturbed. 

Password required" The path's master password or its 
catalog's master password. 

• SPACE- — All empty data spaces on the volume are deleted. The 
DSCB entry that describes each deleted VSAM data space in 
the volume* s VTOC is removed. The space is made available to 
other 0S/VS2 system objects. 

When all VSAM data spaces on the volume have been 
deleted, or when you specify FORCE, its volume entry in 
the catalog is deleted. The volume ownership indicator 
in the volume's VTOC is reset so that a VSAM catalog no 
longer owns the volume. 

When the last data space on a volume is deleted and the 
volume is not a candidate volume, the volume's entry is 
also deleted from the catalog. The effect of deleting 
the volume entry is that the volume is no longer owned 
by the catalog, that is, another catalog is free to 
allocate space on the volume. 

The volume must be mounted. 

You cannot specify the PURGE parameter when you delete 
VSAM data spaces. 

When you identify data spaces to be deleted, you cannot 
identify any other type of cataloged object to be 
deleted with the same command. You can, however, follow 
the DELETE SPACE command with other Access Method 
Services commands. 

Password required* the catalog's update (or 

highei — level) password. When you also specify FORCE, you 

must supply the catalog's master password. 

• USERCATALOG— The catalog's self-describing entries and its 
usei — catalog entry in the master catalog are deleted. The 
DSCB entry that describes the usei — catalog's data space is 
removed from the volume's VTOC. The volume-ownership 
indicator in the volume's VTOC is reset so that the volume 
is not owned by a VSAM catalog. 
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The catalog must be empty — it cannot contain any catalog 
entries, unless you specify FORCE. 

All alias entries in the master catalog that point to 
the usei — catalog connector entry are also deleted. 

You cannot code the ERASE or CATALOG parameters when you 
delete a user catalog. 

The catalog's volume must be mounted. If the volume is 
unavailable or inaccessible, DELETE cannot be used. You 
should use EXPORT DISCONNECT instead. 

You can delete a user catalog and redefine it in the 
same step, but you cannot use the redefined catalog in 
that same step. A TSO session is considered one step so 
you would have to log off and then log on to use a 
catalog that you have deleted and redefined. 

If there i s any possibility of other users accessing a 
user catalog while it is being deleted, you should 
serialize the job or job step that deletes the catalog 
by providing a JOBCAT or STEPCAT DD statement specifying 
the catalog name as dsname and DISP=0LD. 

Password required* the user catalog's master password is 
specified with its entryname. 

You cannot delete a data or index entry separately from its 
associated cluster, alternate index, or user catalog entry. 

If the only object on a VSAM volume is a cluster or alternate 
index that resides in a unique data space, deleting its entry 
does not cause VSAM Volume ownership to be relinquished. The 
volume entry remains in the catalog in a candidate status. You 
must issue a DELETE SPACE command to cause VSAM to release 
ownership of the volume. 

Refer to the chapter "Command Format" for a description of the 
command format for DELETE. Examples of deleting VSAM and nonVSAM 
data sets are also included. 



ORDER OF CATALOG USE: DELETE 



The order in which catalogs are searched when an entry is to be 
located to be deleted is : 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found" error is returned to the user. 

2. Any user catalog(s) specified in the current job step (with 
a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. 

If a STEPCAT catalog is specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 

If no STEPCAT catalog is specified for the job step, and a 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname and 
its first qualifier is the same as-* 

• the name of a user catalog, or 
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• the alias of a user catalog, or 

• the alias of a control volume, 

the user catalog or control volume so identified is 
searched. If the entry is found, no other catalog is 
searched. Otherwise, 

4 . If the entry is not found, the master catalog is searched. 

If the entry is not found in the master catalog, a "no entry 
found" error is returned to the user. 



GENERIC NAMES AND DELETE 



To delete entries with qualified names — for example, 
PAYROLL . 74 .MAY — you can identify the entry with its full name 
(that is, all qualifiers) or with all qualifiers except one. The 
unspecified qualifier is indicated with an asterisk (for 
example, PAYROLL . X .MAY) . This kind of shortened name, 
PAYROLL . *. MAY, is called a generic name. When you specify the 
full entryname, only the entry so identified is modified. When 
you specify all qualifiers of the entryname except one, the 
entries whose entrynames match the supplied qualifiers are 
deleted, if they satisfy other parameters specified with the 
DELETE command's parameters. 

For example, when you specify PAYROLL.*, the entries that might 
be deleted are those whose entrynames contain two qualifiers, 
the first qualifier being PAYROLL. When you specify 
PAYROLL .*. MAY, the entries that might be deleted are those whose 
entrynames contain three qualifiers, the first being PAYROLL and 
the third and last being MAY. 

When you identify a catalog (that is, when you specify the 
DELETE command's CATALOG parameter), Access Method Services 
searches only the specified catalog for generically named 
entries. If no catalog is specified, the catalog is selected as 
indicated in "Order of Catalog Use : DELETE" and is searched for 
generic-named entries. 

You must always specify the first qualifier of a qualified 
entryname. You can substitute an asterisk for no more than one 
of the other qualifiers. 

You must identify all qualifiers in the qualified name. For 
example, PAYROLL.* cannot identify a qualified name that 
contains three or more qualifiers, even though its first 
qualifier is PAYROLL. PAYROLL .74 .MAY.* cannot identify a 
qualified name that has more or fewer than four qualifiers. 
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MOVING ENTRIES 



The EXPORT and IMPORT commands allow you to create backup copies 
of alternate indexes and clusters, to transport user catalogs, 
alternate indexes and clusters from one system to another, and 
to prevent (and subsequently, with the IMPORT command, to allow) 
usage of a user catalog. 

When a user catalog is exported, its catalog-connector entry is 
removed from the master catalog. When the user catalog is 
subsequently imported to a new system, a catalog-connector entry 
is created for it in the new system's master catalog and the 
user catalog is physically transported to the new system. The 
user-catalog volume itself need not be mounted either to export 
or import the user catalog. When a user catalog is exported, it 
is not copied; the user catalog remains on its volume in its 
original form. The user catalog and its cataloged objects are 
unavailable to any user until the user catalog is connected 
(with the IMPORT CONNECT command) to a master catalog. 

You do not have to issue the EXPORT command to allow a user 
catalog to be moved to another system. If the catalog i s on a 
demountable volume, you can physi cally' move the volume to 
another system. You must use an IMPORT CONNECT command to build 
a catalog-connector entry for the user catalog in the new 
system's master catalog. When you issue the EXPORT - DISCONNECT 
command, VSAM removes the usei — catalog's connector entry. 

Note: If you issued the EXPORT DISCONNECT command and your user 
catalog is protected by the RACF Program Product, the RACF 
profile will not be automatically deleted. It is your 
responsibility to remove the profile with RACF utility DELDSD. 
For more information, see the publication 0S/VS2 Resource Access 
Control Facility (RACF) Command Language Reference . 

When a cluster or alternate index is exported, its catalog entry 
is copied to a movable volume along with the object's contents. 
The entries and components are subsequently copied into a new 
system. 

Exportation of a cluster or alternate index is either permanent 
or temporary. In permanent exportation, the catalog record is 
deleted and storage space is freed in the original system. In 
temporary exportation, both the sending and receiving systems 
retain a copy of the object, but the copy in the original system 
is marked to indicate that there is a copy elsewhere. If you 
want to export permanently a base cluster and its associated 
alternate indexes, the alternate indexes must be exported first 
since deletion of a base cluster causes deletion of any 
alternate indexes defined over it. A base cluster must always be 
imported prior to importing any of its alternate indexes. 

When a cluster or alternate index is exported, its catalog 
information (that is, the attributes specified with the DEFINE 
command — except the catalog's name — and modified with subsequent 
ALTER commands) is moved with the cluster's data records. 
However, the statistics kept in the catalog entry are lost (that 
is, the statistics ar& not available when the entry is 
subsequently imported). After the import the statistics stored 
in the catalog entry are the results of the import only. You 
cannot export an empty cluster or alternate index. 

The permanent exportation of a RACF-protected cluster or 
alternate index causes the deletion of the data-set profiles. A 
temporary exportation does not. Also, when a RACF-protected data 
set is exported, the RACF indicators are moved to the portable 
data set, but the profile is not. 
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When a previously exported RACF-protected object is imported, 
you have an option to reuse the old profiles or to establish new 
ones. The IMPORT command in the chapter "Command Format" will 
give you more information on RACF options when importing a VSAM 
object . 

Exporting or importing a RACF-protected catalog will cause no 
change in the status of the RACF indicators in the catalog or 
the profiles associated with the catalog. 

The portable copy of a cluster or alternate index is a 
vari able-blocked* spanned, sequential data set. Each record of a 
relative-record data set contains an 8-byte header. Each record 
of all other types of VSAM data sets contains a 4-byte header. 
The maximum logical record length of the portable data set is 
based on the maximum record size of the VSAM data set to be 
exported. Access Method Services uses the value you specified 
via the maximum subparameter of the RECORDSIZE parameter of the 
DEFINE CLUSTER or ALTERNATEINDEX command when the data set was 
defined. The resulting maximum logical record length of the 
portable data set is as specified below : 

• For relative-record data sets, the greater of 276, or VSAM 
maximum record size + 8 

• For all other types of VSAM data sets, the greater of 272, 
or VSAM maximum record size + 4 

The resulting maximum logical record length of the portable data 
set is limited to 32,760 bytes (Access Method Services does not 
support the DCB parameter, LRECL=X). Therefore, the largest VSAM 
maximum record size which can be handled by EXPORT is: 

• 32,752 for relative-record data sets 

• 32,756 for all other types of VSAM data sets 

If the data set to be exported has been defined with a maximum 
record size greater than the appropriate length shown above, the 
EXPORT command terminates with an error message. 

You may specify, with the DCB parameter of the DD statement for 
the portable data set, a blocksize other than the default of 
2048 bytes. 

Refer to the chapter "Command Format" for a description of the 
command formats for the EXPORT and IMPORT commands. Examples 
showing how data sets are exported and imported ar& also 
included. 
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The EXPORT command is used in conjunction with the IMPORT 
command to move alternate indexes, clusters, and user catalogs 
from one system to another, to provide backup copies of clusters 
and alternate indexes, and to sever the relationship between a 
user catalog and the master catalog. The EXPORT command cannot 
be used to move or provide a backup copy of a master catalog, a 
nonVSAM data set, data space, generation data group, page space, 
or path. Access Method Services automatically exports along with 
a cluster or alternate index any paths defined over it. The 
paths are redefined when the object is subsequently imported. 

If a user catalog is to be exported, the catalog is merely 
disconnected from the master catalog. The user catalog can then 
be physically Cor logically) moved to another system. Even if 
the catalog is not moved to another system, it is temporarily 
unavailable to all users, and its aliases are deleted. The 
person who is responsible for the catalog can issue IMPORT 
CONNECT to make the catalog available again. 



84 0S/VS2 Access Method Services 



You should take care to list the user-catalog's aliases before 
you issue the EXPORT command. You can use the LISTCAT command to 
li st the aliases* 

LISTCAT - 

C AT ALOGC mast ercat name/ password ) - 

ENTRIES (use rcat name) - 

ALL 

The use» — catalog's aliases are listed under the heading 
"ASSOCIATIONS." 

When you use the IMPORT command to make the catalog available to 
another system, you can issue the DEFINE ALIAS command to 
reestablish each of the catalog's aliases. 

When a VSAM cluster or alternate index that has paths defined 
over it is exported, the catalog information for those paths is 
also exported. IMPORT uses this information to reestablish the 
paths in the target catalog. Therefore, EXPORT can be used to 
export path entries, but only as parts of a larger structure 
being exported (that is, a cluster or an alternate index). 



IMPORTING AN ENTRY 



The IMPORT command is used in conjunction with the EXPORT 
command to move a cluster, alternate index, or user catalog from 
one system to another. When a cluster or alternate index is 
imported, it is automatically reorganized. When you move an 
object into the new system, you can change some of its 
attributes (as described with the OBJECTS subparameters) . 

When a user catalog is moved into a system, you may connect it 
to the master catalog in the new system, thereby making the user 
catalog available in the new system. The user catalog might have 
been disconnected to make it temporarily unavailable to users 
even though its volume is not moved. The person who is 
responsible for the catalog can issue IMPORT CONNECT to make it 
avai lable agai n . 

A cluster, alternate index, or user catalog cannot be moved into 
a system if its name or the names of any of its components is 
the same as any name that already exists in the receiving 
catalog. There are two exceptions to this : 

• When IMPORT is used to replace a cluster or alternate index 
with its backup copy. When the object's backup copy was 
made, its catalog entry was marked temporary (that is, 
TEMPORARY was coded when the object was exported). The 
object's temporary entry is deleted when it is imported; a 
new entry is built and imported in place of the temporary 
entry. 

• When the cluster or alternate index has been predefined in 
the receiving catalog. The predefined entry must be for an 
empty data set. If a duplicate entryname exists for an empty 
data set, IMPORT assumes that this is a predefined entry 
whose attributes and space allocation are to be used in 
place of those in effect when the data set was exported. 

If duplicate entrynames are found and the entry in the receiving 
catalog is not marked as temporary and is not empty, the IMPORT 
command is terminated. 

The first record of the copy to be imported causes an entry to 
be defined in the receiving system. A check is made for a 
duplicate name; if a duplicate name exists and is marked 
temporary, the duplicated name is deleted from the receiving 
system so that the new entry can be defined. The deletion takes 
place even if the request for import cannot subsequently be 
completed. 
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A check is also made for an empty target data set. If such a 
data set is present* IMPORT makes no attempt to define a 
replacement data set. Instead, IMPORT copies the data records 
from the portable data set into the empty target data set. If 
you wish to import into an empty target data set, you must 
specify the INTOEMPTY parameter. 
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CONVERTING AN OS CATALOGS ENTRIES TO VSAM CATALOG ENTRIES 



When you want to use the entries in an OS catalog with your 
0S/VS2 system, you can either establish a connector in the 
master catalog to the OS catalog or you can convert the OS 
catalog entries to VSAM catalog entries. (Note: The OS catalog 
is called a control volume or CVOL.) You can convert the OS CVOL 
entries to VSAM catalog entries using one of two methods* 

• Use the DEFINE command to convert some of the entries in an 
OS CVOL to VSAM catalog entries. 

• Use the CNVTCAT command to convert all of the entries in an 
OS CVOL to VSAM catalog entries in a user or master catalog. 

Refer to chapter "Command Format" for a description of the 
command format for CNVTCAT. Examples are also included. 

CONNECTING AN OS CVOL TO THE MASTER CATALOG 

When you want to use an OS CVOL in an 0S/VS2 system, you must 
define the CVOL in the system's master catalog. For a 
description of how this is done, and how OS CVOLs are used in an 
0S/VS2 system, see QS/VS2 Using OS Catalog Management with the 
Master Catalog ; CVOL Processor . 

USING THE DEFINE COMMAND TO CONVERT SOME OF THE CVOL'S ENTRIES 

When you issue the DEFINE command to redefine, in a VSAM 
catalog, objects cataloged in an OS catalog (that is, OS CVOL), 
you can : 

• Selectively catalog entries from the OS catalog 

• Convert a large OS catalog to two or more VSAM catalogs, 
without first splitting the OS catalog 

However, this method requires that you issue (that is, keypunch 
or type in) many DEFINE commands. To lessen the amount of 
keypunching, you might use the following procedure 1 

1. Execute the IEHLIST utility program to list the OS catalog. 
The output of the program is the input to step 2. The 
IEHLIST program is described in detail in 0S/VS2 MVS 

Uti lities . 

2. Write and execute* 

• A program to generate DEFINE ALIAS statements for each 
CVOL pointer entry and alias entry in the OS CVOL 

1 i st i ng. 

• A program to generate DEFINE ALIAS statements for each 
CVOL pointer entry that relates the CVOL pointer names 
to the appropriate catalog name. 

• A program to generate DEFINE NONVSAM statements for each 
nonVSAM data set in the OS CVOL listing. 

• A program to generate DEFINE GENERATIONDATAGROUP 
statements for each generation-index pointer entry in 
the OS CVOL listing. 

The output of step 1 (the IEHLIST listing) is the input 
to your program. The output of your program is a series 
of DEFINE ALIAS, DEFINE NONVSAM, and DEFINE 
GENERATIONDATAGROUP commands. 
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3. Select the DEFINE statements that represent the entries you 
want cataloged in one of the VSAM catalogs. 

4. Code and execute the appropriate JCL statements to execute 
the Access Method Services program, IDCAMS, using the 
selected DEFINE statements from step 3 as SYSIN input 
statements. 

5. Repeat steps 3 and 4 until you have selected and cataloged 
as many entries as you want in the appropriate VSAM 
catalogs. CVOL aliases must be put in the VSAM master 
catalog. 

USING THE CNVTCAT COMMAND TO CONVERT ALL OF THE OS CVOL'S ENTRIES TO VSAM 
CATALOG ENTRIES 

The CNVTCAT command is used to convert entries in an OS catalog 
to entries in an existing master or user catalog. CNVTCAT 
converts data-set entries, generation data group entries, alias 
entries, and CVOl-pointer entries to appropriate VSAM catalog 
entries. 

CNVTCAT was designed to be executed only once for an OS catalog. 
The execution of CNVTCAT is time-consuming for any catalog 
greater than one hundred entri es. Therefore, you should not plan 
to repeatedly convert the entries of a large OS catalog. 

When an OS catalog structure of a system catalog and many OS 
CVOLs sre converted to a VSAM master catalog and many user 
catalogs, you can use Access Method Services commands to perform 
the entire operation. You can also merge an OS CVOL's entries 
into a VSAM catalog, using the CNVTCAT command. However, you 
cannot easily divide the entries of a large OS catalog among 
many' VSAM user catalogs. When the OS catalog is organized on the 
basis of qualified data-set names, you can split the OS catalog 
into two or more OS catalogs using the IEHMOVE function of a 
selective COPY CATALOG command. You can then convert the entries 
of the smaller OS catalogs into selected VSAM catalogs. When the 
OS catalog is not organized by qualified data set name, you can 
catalog each individual entry using the DEFINE command as 
illustrated in the section "Using the DEFINE Command to Convert 
Some of the CVOL's Entries." 

OS control volumes (CVOLs) can be interchanged within different 
operating systems: 0S/VS2-1, 0S/VS2-2, and 0S/VS2-3. When you 
intend to continue production on another operating system while 
converting to 0S/VS2, you might want to use OS CVOLs because 
they can be transferred between operating systems. 

When you catalog an OS CVOL in the system's master catalog, you 
can use the CVOL to point to its cataloged entries. You cannot 
use a STEPCAT or JOBCAT DD statement to identify an OS CVOL, 
however; an OS CVOL and a VSAM user catalog might reside on the 
same volume, since the CVOL is considered a nonVSAM data set. 

You can issue the DELETE ALIAS command to delete a CVOL's alias 
in the master catalog. When you issue the DELETE NONVSAM command 
to uncatalog the OS CVOL, all of its aliases are also deleted. 

Figure 4 shows OS catalog-entry types, abbreviations, 
descriptions, and the VSAM entry types into which OS catalog 
entries &r& converted. 
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Entry Name Abbreviation Description VSAM Entry Type 

Alias entry AE Contains an Alias entry. 

alternate name for 
the high-level 
qualifier of the 
data set name 

Control volume CVPE Connects another Alias entry for a user 

pointer entry control volume catalog in master 

(CVOL) to this catalog. 

CVOL 

Data-set entry D5PE Contains the name NonVSAM entry, 

pointer and location of a 

data set 

Generation GIPE Points to the Generation data group, 

index pointer lowest index for a 

entry generation data 

group 

Generation data G0000V00 Points to a NonVSAM entry that is 

set generation data set attached to a generation 

data group. 

Figure 4. OS Catalog Entry Types and VSAM Equivalents 



When you use the CNVTCAT command, you can cause all the entry 
types shown in Figure 4 to be converted or all but the 
control-volume-pointer entries (CVPEs) to be converted. CVPEs 
are converted to alias entries in the master catalog. If, for 
example, ABC was the name of a control volume (CVOL) that 
resided on volume 123456, ABC becomes the alias in the master 
catalog; you provide the name of the VSAM catalog for which ABC 
is an alias. 

Because CNVTCAT creates aliases for CVPEs, converted OS catalog 
entries can be found without a STEPCAT or JOBCAT DD statement 
that identifies the VSAM catalog to be searched. If, for 
example, ABC. DEF, which was previously contained in an OS 
catalog, is to be found : 

1. Master catalog is searched because no STEPCAT or JOBCAT is 
speci f i ed. 

2. ABC is found in the master catalog; it i s an alias that is 
related to a user-catalog entry. 

3. Usei — catalog entry points to the user catalog. 

4. ABC. DEF is found as a nonVSAM entry on the user catalog. 

Figure 5 shows an OS catalog, SYSCTLG that contains two CVPEs 
and shows the CVOLs that they point to. Before you can convert 
the CVPEs, you must be able to provide their volume serial 
numbers. To learn the volume serial numbers, list the OS catalog 
to be converted. If SYSCTLG, shown in the top half of Figure 5 
is converted, aliases, SYSA and SYSB are created in the master 
catalog. In a separate conversion, the data sets cataloged in 
SYSA and SYSB are converted into entries in existing VSAM 
catalogs. The bottom half of Figure 5 shows the master catalog 
and two user catalogs after SYSCTLG and SYSA and SYSB have been 
converted. 

The amount of space required in the VSAM catalog depends upon 
the number and kind of records converted. Each OS catalog entry 
converts to a nonVSAM entry in a VS catalog. The exception is 
alias entries. One alias entry in an OS catalog can apply to 
many data-set names. When the alias is converted, one alias 
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Figure 5. Converting Control Volume Entries 



entry is created in the VSAM catalog for each data set that has 
the high-level qualifier to which the alias applies. For 
example, an alias, FAKE, exists for REAL. If REAL. A, REAL.B, and 
REAL.C are converted, a total of six records are required in the 
VSAM catalog^ one record is required for each of the three data 
sets and one record is required for each of three aliases, one 
p&r data set. See "Estimating the Catalog's Space Requirements" 
to help you estimate the VSAM catalog's size. 

Note 5 Control volumes can be used in a VS2 system without 
converting entries. See 0S/VS2 Using OS Catalog Management with 
the Master Catalog- CVOL Processor for information about the use 
of control volumes in a VS2 system. 
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ORDER OF CATALOG USE: CNVTCAT 



The order in which VSAM catalogs are evaluated to select the 
catalog that receives the converted entries is: 

• If a catalog is specified in the CATALOG parameter, that 
catalog receives the converted entries. Otherwise, 

• The user catalog specified for the current job step 
(STEPCAT) or, if none is specified for the job step, the 
user catalog specified for the current job (JOBCAT) receives 
the converted entries. (If more than one catalog is 
specified for the job step or job, the first catalog in 
order of concatenation is selected.) Otherwise, 

• The master catalog receives the converted entries. 

The master catalog always receives alias entries that point to 
user catalogs. 
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RESTORING A CLUSTER'S END-OF-FILE VALUES 



When a data set is closed, its end-of-file (EOD) and 
end-of-key-range (EOKR) information is used to upgrade EOD and 
EOKR information in the data set's cataloged information. If an 
OS/VS system failure occurs before the data set is closed (that 
is, before the user's program issues CLOSE or CLOSE(TYPE=T) ) , 
the data set's cataloged information is not upgraded. This means 
that the data set's cataloged information contains possibly 
obsolete EOD and EOKR information. The data set's real EOD and 
EOKR indicators are written in the data set, but are not shown 
in the data set's cataloged information. When the data set is 
subsequently opened and the user's program attempts to process 
records EOD or EOKR, a "no record found" error results on a read 
operation, and a write operation might write records over 
previously written records. 

The VERIFY command is used to compare the end-of-data-set and 
end-of-key range information as it is stored in a VSAM catalog 
with the true end-of-file and end-of-key range. If the 
information in the catalog does not agree with the true 
end-of-file or end-of-key range, the catalog information is 
corrected. The VERIFY command can be used following a system 
failure that caused a component opened for update processing to 
be improperly closed. Clusters, alternate indexes, and catalogs 
can be verified. Paths over an alternate index cannot be 
verified. Paths defined directly over a base cluster can be 
verified. Although the data and index components of a 
key-sequenced cluster or alternate index can be verified, the 
timestamps of the two components will be different following the 
separate verifies, possibly causing further OPEN errors'. 
Therefore, you should use the cluster or alternate index name as 
the target of your VERIFY command. 

To use the VERIFY command to verify a catalog, Access Method 
Services must be authorized. See "Authorized Program Facility 
(APF)" in QS/VS2 System Programming Library? Supervisor for 
information about program authorization. 

A user catalog is opened as a data set, when restoring its 
end-of-file and end-of-key-range information. A JOBCAT or 
STEPCAT DD statement must therefore be supplied. 

Refer to the chapter "Command Format" for a description of the 
command format for the VERIFY command. 
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RESTORING CATALOG ENTRIES AFTER SYSTEM FAILURE 



When you create a user catalog or a master catalog, you can 
define it as recoverable. A recoverable catalog has, on each 
volume it owns, an area that contains a copy of some of the 
catalog's entries. Each volume's area is called the catalog 
recovery ar&a or CRA. When a system or device failure occurs 
that damages the catalog or some of its entries, each volume's 
catalog recovery area contains the information needed to restore 
the damaged entries. The contents of a volume's catalog recovery 
area depend on the types of objects the volume contains. 
Figure 6 identifies the volume whose catalog recovery area 
contains a copy of the cataloged object. 



Volume Whose Catalog Recovery Area 
Type of Entry Contains a Copy of the Catalog Entry 

Volume entry Its own volume 

Key-sequenced cluster entry and The volume that contains the (first 
its data and index entries part of the) cluster's index component 

Alternate-index entry and its The volume that contains the (first 

data and index entries, when the part of the) alternate index's base 

alternate index is for a cluster's index component 
key-sequenced cluster 

Path entry, when the path is The volume that contains the (first 

related to a key-sequenced cluster part of the) path's base cluster's 

index component 

Entry-sequenced cluster's entry The volume that contains the (first 
and its data entry part of the) cluster's data component 

Alternate-index entry and its data The volume that contains the (first 
and index entries, when the part of the) alternate index's base 

alternate index is for an cluster's data component 

entry-sequenced cluster 

Path entry, when the path is The volume that contains the (first 

related to an entry-sequenced part of the) path's base cluster's 

cluster data component 

Relative-record cluster entry and The volume that contains the (first 
its data entry part of the) cluster's data component 

NonVSAM data set The volume that contains the nonVSAM 

entry's catalog 

Generation Data Group The volume that contains the entry's 

catalog 

Alias Entry The volume that contains the catalog 

in which the nonVSAM association for 
the alias is defined 

Usei — catalog connector entry in The volume that contains the master 
the master catalog catalog 

Catalog's self-describing entries These entries are not duplicated 

in any catalog recovery area 

Figure 6. Catalog Recovery Area Contents 
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If you should discover that your recoverable catalog is damaged 
such that its entries are inaccessible, are downlevel, or 
contain erroneous information, you have the option of choosing 
one of two different methods to restore your catalog to a usable 
condi ti on. 

• The EXPORTRA/IMPORTRA Method: You would most likely use 
this method to selectively repair specific catalog entries. 
Also, remember that reorganization of your catalog and your 
data is a byproduct of this approach since it involves the 
movement of data. You may use the following procedure to 
restore the usability of your catalog. 

1. Issue the LISTCRA command to list and, optionally, 
compare the catalog recovery area entries (that is, the 
catalog recovery area that contains copies of the 
damaged catalog entries). 

2. Issue the EXPORTRA command to obtain a copy of the 
damaged entries from the catalog recovery area and, when 
a VSAM data set entry is moved, obtain a copy of the 
data set' s co.ntents. 

3. Clear the damaged volume or reset it so that it is 
usable by doing one or more of the following- 
Issue the DELETE SPACE command with the FORCE 
parameter to remove VSAM data spaces from the 
volume. 

Execute the IEHDASDR program with the DUMP and 
RESTORE statements to restore nonVSAM data sets on 
the volume. (See QS/VS2 MVS Utilities for details.) 

Execute the IEHDASDR program with the ANALYZE 
statement to initialise the volume. (See QS/VS2 MVS 
Utilities for details.) 

Issue the ALTER REMOVEVOLUMES command to remove the 
VSAM catalog's ownership of the volume. 

4. Issue the IMPORTRA command to reload the data copied and 
moved during step 2 above. 

• The RESETCAT Method 1 If you do not want your data to be 
moved and if you wish to confine all updating to the catalog 
(and CRAs), you should consider this approach. RESETCAT' does 
not permit selective reset of specific catalog entries. An 
entire volume's worth of catalog entries are reset. You 
would use RESETCAT if a catalog or one or more of its owned 
volumes become inaccessible. Restore the volume(s) from a 
backup copy and issue RESETCAT to provide the necessary 
consistency between the catalog and the restored volume(s). 

The LISTCRA, EXPORTRA, IMPORTRA, and RESETCAT commands are 
described in detail in the sections that follow. 



LISTING THE CATALOG RECOVERY AREA'S CONTENTS 

If your catalog was created with the RECOVERABLE option, you can 
determine the damage (if any occurred) that was done to your 
catalog when a system or hardware failure occurred. You can also 
determine if a volume or volumes owned by your catalog is 
out-of-synchroni zat i on with the catalog itself (caused, for 
example, by restoring a volume from a downlevel backup). This is 
because a recoverable catalog maintains a copy of each catalog 
entry in a separate part of the volume* called the catalog 
recovery area (CRA). 
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When you issue the LISTCRA command with the COMPARE parameter, 
Access Method Services compares each entry in the CRA to its 
corresponding entry in the catalog. The comparison is made on a 
record-by-record, byte-by-byte basis. When a mismatch is 
encountered within a record, Access Method Services determines 
the field within the record in which the mismatch exists and 
prints a message. For certain fields, the message identifies the 
field(s) which mismatched. (The section "Regaining Access to 
Data" lists the mismatches detected by LISTCRA.) 

When a mismatch is detected, Access Method Services prints both 
the catalog record and the corresponding CRA record. Asterisks 
are printed below the specific area which showed a mismatch. All 
records associated with the mismatched record are also printed 
(for example, a volume record and its extensions). You can use 
the LISTCRA output listing to determine which catalog entries 
are no longer accurate, and to help you code the ENTRIES 
subparameter of the EXPORTRA command. 

To use the LISTCRA command, Access Method Services must be 
authorised. See "Authorized Program Facility (APF)" in DS/VS2 
System Programming Library: Supervisor for information about 
program authorization. 

The types of output listing that the LISTCRA command can 
produce, depending on the optional parameters, are: 

• A list of the name and volser of each entry, and the name 
and volser of each related entry, in the catalog recovery 
area. The entries are listed in alphameric order by group 
type (NOCOMPARE and NAME). 

• A full dump (that is, hexadecimal and character listing) of 
each entry and its related entries in the catalog recovery 
area. The entries are listed in alphameric order by group 
type (NOCOMPARE and DUMP). 

• A list of the name of each catalog entry and its volser 
whose data does not compare equally with the entry's copy in 
the catalog recovery area, and an indication of the type of 
information that miscompares. The mi scompared entries are 
listed in alphameric order by group type. The entries that 
compare equally are not listed (COMPARE and NAME). 

• A full dump (that is, hexadecimal and character listing) of 
each catalog record whose contents does not compare equally 
with the record's copy in the catalog recovery area, and 
asterisks below each byte that mismatches. The mismatched 
entries are listed in alphameric order by group type. Refer 
to the section "Regaining Access to Data" in the chapter 
"Data Security and Protection" for a description of the 
types of mismatches detected by LISTCRA. The entries that 
compare equally are not listed (COMPARE and DUMP). 

• A full dump (that is, hexadecimal and character listing) of 
all entries in the catalog recovery area in sequential order 
as they occur in the CRA (SEQUENTIALDUMP) . "Appendix D. 
Interpreting LISTCRA Output Listings" provides a description 
of LISTCRA outputs. 

Refer to the chapter "Command Format" for a description of the 
command format of LISTCRA. An example is also included. 
"Appendix D. Interpreting LISTCRA Output Listings" provides a 
description of LISTCRA output. 



Restoring Catalog Entries after System Failure 95 



COPYING A CATALOG ENTRY FROM THE CATALOG RECOVERY AREA 

When you discover that your catalog is partially or completely 
damaged due to a system failure or hardware problem, you want to 
reconstruct the damaged catalog entries so that you can access 
the cataloged object's data. When you discover that some of the 
entries in your catalog are not in synchronization with volumes 
the catalog owns, you want to resynchroni ze the incorrect 
entries so they properly reflect the actual status of the 
volumes. You can rebuild a catalog entry by issuing the IMPORT 
command when you have recently made a copy of the object with 
the EXPORT command. The IMPORT command replaces the damaged 
catalog entry with its copy in the exported file. (See "Moving 
Entries" for details about the EXPORT and IMPORT commands. ) 

An exported copy of your cluster might not exist, or the one you 
have might not be current. The volume that contains your data 
might not be damaged but, because its catalog entry is damaged 
or out-of-synchroni zati on, you cannot use the catalog entry to 
locate and access your data. What you want to do is replace the 
damaged catalog entry with its undamaged copy in the catalog 
recovery area and, when the entry is for a VSAM data set, to 
move the contents of the data set to a volume owned by an 
undamaged catalog. For a recoverable catalog, you can use the 
EXPORTRA command to obtain the catalog-entry's copy from the 
catalog recovery area, then use the IMPORTRA command to replace 
the damaged entry with its copy. 

If an entire VSAM volume becomes unusable, and a backup copy of 
the volume exists, you may want to consider using RESETCAT 
rather than EXPORTRA to reset your catalog so that it will 
correctly access the VSAM data sets on the restored volume. See 
"Resetting Catalog Entries." 

To use the EXPORTRA command, Access Method Services must be 
authorized. See "Authorized Program Facility (APF)" in 0S/VS2 
System Programming Library* Supervisor for information about 
program authorization. 

When a VSAM data set is recovered using the EXPORTRA and 
IMPORTRA commands, the result is essentially the same as if the 
data set were backed up using the EXPORT and IMPORT commands. 
The differences in the process used to achieve this result are- 

• The data set's catalog entry is copied from a catalog 
recovery area instead of the VSAM catalog. 

• Many data sets can be recovered with one issuance of the 
EXPORTRA and IMPORTRA commands. 

The EXPORTRA command copies VSAM catalog entries and the 
contents of nonempty VSAM data sets to a movable storage device 
(that is, a magnetic tape or demountable disk pack). Other 
capabilities of the EXPORTRA command that are not available as 
functions of the EXPORT command are: 

• All entries in a catalog recovery area can be copied, 
including VSAM clusters and alternate index entries, VSAM 
user catalog connectors and their aliases (from a master 
catalog CRA only), GDG base entries, and nonVSAM entries and 
their aliases. The connection between a nonVSAM entry and 
its GDG base entry is mentioned in the copy. Page spaces are 
not copi ed. 

• You can copy the entries for an empty cluster or alternate 
i ndex. 

• You can obtain a copy of each entry in the catalog recovery 
area by issuing the EXPORTRA command once. Subsequently, you 
can replace all entries exported with the EXPORTRA command 
by issuing the IMPORTRA command once. 
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• You can obtain the copy of one or more entries, as you 
specify, without obtaining the rest of the catalog recovery 
area . 

• When the catalog owns more than one volume, you can obtain 
the copy of each entry from one volume's catalog recovery 
area without obtaining entries from the catalog recovery 
areas of other volumes. 

Use of the EXPORTRA command is limited to a single execution per 
system at one time only. That is, multiple executions cannot be 
processed simultaneously. 

The EXPORTRA command uses the variable-blocked spanned 
sequential format (SAM RECFM = VBS) for its output data set. 
Each record contains an 8-byte header. Each data record of a 
VSAM relative-record data set contains an additional 4-byte 
header. EXPORTRA sets the maximum logical-record length of the 
output data set based on the largest maximum recordsize of all 
the VSAM data sets being copied. To determine the largest 
maximum record size, EXPORTRA uses the value specified via the 
maximum subparameter of the RECORDSIZE parameter of the DEFINE 
CLUSTER or ALTERNATEINDEX command when each of the data sets to 
be exported was defined. The resulting maximum logical record 
length of the output data set is as specified below: 

• If a VSAM relative record data set has the largest maximum 
record size, the greater of 280, or the largest VSAM record 
size + 12 

• If a VSAM key-sequenced or entry-sequenced data set has the 
largest maximum record size, the greater of 280, or the 
largest VSAM maximum record size + 8 

The resulting maximum logical-record length of the output data 
set is limited to 32,760 bytes (Access Method Services does not 
support the DCB parameter LRECL=X). Therefore, the largest VSAM 
record which can be handled by EXPORTRA is: 

• 32,748 for relative record data sets 

• 32,752 for all other types of VSAM data sets 

If any of the VSAM data sets to be exported has been defined 
with a maximum record size greater than that shown above, the 
EXPORTRA command terminates with an error message. 

You may specify, with the DCB parameter of the DD statement for 
the portable data sets, a block size other than the default of 
2048 bytes. 

If the EXPORTRA command is executed for a RACF-protected VSAM 
entity, the RACF indicator will be exported on to the portable 
data set. However, profiles will not be deleted, nor will the 
profiles be moved to the portable data set. When RACF-protected 
VSAM entities are imported using IMPORTRA, you have an option to 
reuse the old profiles or to establish new ones. 

The EXPORTRA command requires a DD statement for each volume to 
be accessed; all volumes must be mounted. EXPORTRA does not 
dynamically allocate the required volumes. 

Refer to the chapter "Command Format" for a description of the 
command format for EXPORTRA. Examples of EXPORTRA are included 
with the EXPORTRA command format in the same chapter. 
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RESTORING THE CATALOG ENTRY THAT HAS OBTAINED USING THE EXPORTRA COMMAND 

The IMPORTRA command is used to reestablish in a catalog all 
those objects that reside in the portable data set created by a 
previously issued EXPORTRA command. When an existing catalog 
entry is found with the same entryname as the object in the 
portable data set, the existing entry is first deleted. The 
object is redefined in the catalog, using information from the 
portable data set. 

VSAM clusters, their associated data and index components, and 
any paths over them, alternate indexes, their associated data 
and index components, and any paths over them, nonVSAM data 
sets, and generation data group entries are automatically 
defined in the catalog selected by the user. If a VSAM cluster 
or alternate index was not empty at the time the EXPORTRA 
command was issued, its data records were copied to the portable 
data set together with its VSAM catalog entries. These data 
records are reloaded into the space occupied by the redefined 
object. User catalog connector entries (which can be exported 
only from the system's master catalog) are connected to the 
master catalog. (Existing user catalog-connector entries with 
the same entryname as the imported entry are disconnected rather 
than deleted; the imported user catalog-connector entry is then 
reconnected.) The aliases of user catalog and nonVSAM entries 
are also redefined by IMPORTRA. 

IMPORTRA requires you to provide a DD statement (specified 
through the OUTFILE parameter) which identifies a data-set name 
and the volume serial number of each volume that is to contain 
the imported VSAM clusters or alternate indexes. You must use 
concatenated DD statements if the data sets are on different 
device types. The data-set name you specify is used by Access 
Method Services for its internal processing during the execution 
of the IMPORTRA command. The sequence of processing steps is 
shown below : 

1. The cluster or alternate-index catalog information is 
obtained from the portable data set (created by EXPORTRA). 

2. The cluster or alternate index is defined in the catalog. 

3. If an existing catalog entry with the same entryname is 
found, the existing entry is deleted. The cluster or 
alternate index is then redefined in the catalog. 

4. The cluster or alternate index entry in the catalog is 
renamed using the data-set name you provided in the DD 
statement identified in your OUTFILE parameter. 

5. The cluster or alternate index is opened, loaded with its 
data records, and closed. 

6. The cluster or alternate-index entry is renamed to the 
original name contained in the portable data set. 

If a system failure should occur after step 4 and prior to the 
successful completion of step 6, the data set may exist in the 
VSAM catalog under the name provided on the DD statement. To 
correct the situation, you can delete the cluster or alternate 
index using the data-set name you provided in the DD statement 
prior to rerunning the IMPORTRA command. 

Refer to the chapter "Command Format" for a description of the 
command format for IMPORTRA. Examples of EXPORTRA and IMPORTRA 
are included. 
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RESETTING CATALOG ENTRIES 



When you define a catalog as recoverable, each volume owned by 
the catalog contains a catalog recovery area (CRA). The CRA 
contains duplicate information for catalog entries associated 
with that volume. You can use the RESETCAT command when a 
recoverable catalog or one or more of its owned volumes becomes 
inaccessible. You can restore the inaccessible volume(s) from a 
backup copy and execute the RESETCAT command. The CRAs contain 
enough information to reset the catalog entries, and VSAM data 
sets owned by that catalog can again be accessed correctly. 

Unlike the EXPORTRA/IMPORTRA command, the RESETCAT command is a 
one-step operation that enables you to recover your catalog 
without movement of data. The RESETCAT command does not check or 
process the data itself, but compares catalog entries with CRA 
entries and resets as necessary in order to enable you to regain 
access to the data. You are responsible for ensuring that the 
data is at the correct level for your use. 

If a VSAM volume becomes inaccessible, and a backup copy of the 
volume is used to restore the volume to a previous level, the 
volume and the catalog may no longer be synchronised. A list 
created by the LISTCRA command (with COMPARE option) can 
i ndi cate mi smatches that require RESETCAT command to be run. The 
RESETCAT command can synchronize the catalog with the volume. 
After access to the data has been regained, the data sets on 
that volume can be brought up to the current level by rerunning 
the jobs that were run after the backup was taken. 

If a recoverable catalog becomes unusable, use the LISTCRA 
command to help analyze the problem (also see "Catalog 
Recovery"). If you are unable to access your data, restore the 
catalog volume. Then run the RESETCAT command to synchronize the 
catalog with its owned volumes. If volumes have been added since 
the catalog backup was made, RESETCAT can build these entries in 
the catalog from the volume's CRA. If volumes have been deleted 
since the last backup, use the DELETE SPACE (FORCE) command to 
delete the volume's space entries in the catalog and delete the 
data sets that resided on those volumes that are now marked 
unusable in the catalog. 

RESETCAT uses the entries in the catalog recovery ar&a for each 
volume you identify to synchronize the catalog with these 
volumes. The actions taken by RESETCAT to accomplish this 
synchronization are summarized below : 

• If an entry exists in the catalog but not in the CRA, the 
entry is deleted from the catalog. 

• If an entry exists in the CRA but not in the catalog, the 
entry is inserted into the catalog. 

• If, in adding an entry to the catalog a duplicate name is 
encountered, the entry to be added is renamed. If the data 
or index component of a unique cluster or alternate index is 
renamed, the corresponding f ormat-1 DSCB i s also renamed. If 
a nonVSAM entry is renamed, the corresponding format-1 DSCB 

i s not renamed. 

• The data space accounting in the volume entry is checked 
against the Volume Table of Contents (VTOC). 

If the VTOC contains a format-1 DSCB for VSAM space but 
the CRA volume entry does not reflect this space, the 
format-1 DSCB is scratched. 

If the CRA shows space which is not reflected in a 

format-1 DSCB, the space is deleted from the CRA volume 

entry and the VSAM data sets which were shown as being 
contained within the space are marked unusable. 
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If the extents in the CRA volume entry do not match 

those in the associated format-! DSCB, the CRA is 

adjusted. ( 

• A space consistency check is performed to ensure that the 
space claimed by a VSAM data set has the correct extents. If 
a data or index component claims space that is not allocated 
to VSAM, the component is marked unusable. If a data or 
index component claims space which is in conflict with 
another claim, the component in error is marked unusable and 
all space not shown as claimed will be returned for 
suballocati on. 

• An association check is performed to ensure completeness of 
the structures; for example, a cluster entry must be 
correctly associated with its data and index components. 
When a structure is found to be incorrect, it is deleted and 
its space returned for suballocati on . If a base cluster 
association is incorrect, the entire structure (base 
cluster, all alternate indexes, and paths) is. deleted. If an 
index structure is incorrect, only the alternate 
alternate-index structure and its paths are deleted. 

Whenever RESETCAT takes action as indicated above, you are 
informed with appropriate messages. 

If your catalog becomes unusable and no backup copy i s 
available, you can use RESETCAT to recover all of your catalog 
entri es* 

If the catalog is a user catalog, remove the catalog 
connector entry of your catalog from the master catalog via 
EXPORT DISCONNECT, and define a catalog with the same name 
on a different volume with the RECOVERABLE attribute. The 
new catalog can be on a different device type. You may 
specify a different allocation from that of the original 
catalog. Volumes owned by the unusable catalog should not be 
included as owned by the new catalog. The DEFINE operation 
would flag this as an error condition, because volumes are 
already owned. 

With this new catalog, issue RESETCAT, specifying all 
volumes owned by the previous catalog (including the 
unusable catalog's resident volume) for reset. Because the 
new catalog name is the same as the old catalog name, all 
entries in the specified CRAs will be added to the new 
catalog (including volume entries). At the conclusion of 
RESETCAT processing, the old catalog will have been deleted 
and the space freed for suballocati on . 

While the catalog is always updated during RESETCAT processing, 
the CRA can also be updated under certain circumstances. If some 
external event such as a power failure were to cause RESETCAT to 
fail, partial updates to the catalog and CRA(s) may have taken 
place. Therefore, the catalog and any CRA volumes being reset 
should be restored before RESETCAT is rerun. It is advisable, 
therefore, for you to have backup volumes of your catalog and 
CRA(s) before you use RESETCAT. 

Prior to running RESETCAT, you may also wish to execute a 
LISTVTOC for the volumes to be used in the reset operation 
(because the VTOC may be changed by RESETCAT). Also, you may 
wish to execute a LISTCAT command for the catalog to be reset. 

After RESETCAT processing has completed, you should examine the 
messages it has issued. These messages describe specific actions 
taken by RESETCAT, such as marking a data set unusable or 
deleting an incorrect VSAM structure. You may also find it 
advisable to execute a LISTCRA command with the COMPARE option 
to verify that no further mismatches exist. 

Any further action you should take depends on each message 
issued by RESETCAT. If a data set has been marked unusable, the 
data that is accessible can be copied using the REPRO command. 
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Data sets marked unusable can be deleted using the DELETE 
command. If renaming has taken place, you may wish to alter the 
name selected by RESETCAT to a more meaningful name using the 
ALTER command with the NEWNAME option. 

Refer to the chapter "Command Format" for a description of the 
command format of RESETCAT. Examples are also included. 



RESETCAT REQUIREMENTS 



In planning to use RESETCAT, you should be aware of the 
following requirements 1 

• Access Method Services must be authorized. See "Authorized 
Program Facility (APF)" in 0S/VS2 System Programming 
Library* Supervisor for information about program 
authori zat i on. 

• The catalog being reset must be capable of being opened 
(that is, any errors terminating OPEN must be resolved 
before using RESETCAT), and it must have the RECOVERABLE 
attribute. It may or may not have valid entries. 

• The CRAs must be capable of being opened (that is, any 
errors terminating OPEN must be resolved before using 
RESETCAT). Entries not related to the CRA itself may be 
inaccessible. 



The CRAs must have been created by a recoverable catalog 
with the same name as the catalog being reset. 

The catalog must be extendable in the event that it becomes 
enlarged as a result of the reset operation. 

If the master catalog is password protected, the master 
password of that catalog is required. 

The master catalog may not be reset while it is in use as a 
master catalog. 

No VSAM data sets cataloged in the catalog being reset can 
be open. 

You need to use caution when using RESETCAT to recover 
accessibility of a volume which contains a portion of a 
multivolume file. Prior to issuing RESETCAT, compatible 
levels of volumes containing multivolume files should be 
restored. See "Considerations for Multivolume Data Sets" in 
this chapter for more details. 



WORKFILE SPACE REQUIREMENTS 



The RESETCAT command requires a temporary work file for use as 
temporary storage while processing the command. It is defined by 
the RESETCAT command in a catalog other than the one being reset 
and deleted at the end of command processing. The space required 
is suballocated from VSAM data spaces on the volumes assigned on 
the DD statement for the WORKFILE parameter. Under normal 
conditions (no extensions), the amount of space required will be 
no larger than the resultant catalog. You can determine this by 
a LISTCAT listing of that catalog. 

If the catalog must be extended as a result of RESETCAT 
processing (this may occur when the catalog is restored at a 
lower level than its owned volumes), enough data space must be 
provided to allow for this extension. The space required for 
each extension is 6603 records, where the record size is 505 
bytes. An additional 7 bytes per record will be required; the CI 
size will be set at 512 bytes. 
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CONSIDERATIONS FOR MULTIVOLUME DATA SETS 



The contents of a volume's CRA depend on the types of objects 
the volume contains. It is important for you to understand on 
which CRA the catalog information resides for a particular 
object. Figure 6 in this chapter i dent i fies by object type the 
location of the CRA. 

The primary CRA contains all of the catalog records necessary to 
describe the object. Hence, for an entry sequenced data set on 
two volumes, the volume that contains the first part of the 
entry-sequenced data set contains all the records that describe 
the entry entry-sequenced data set ( including its allocation on 
the second volume). The second volume, a secondary CRA for this 
object, contains information that shows that the entry-sequenced 
data set is allocated on the second volume. If the second volume 
has an I/O error that renders it useless and a previous version 
of that volume is restored, the present catalog information may 
be erroneous; that is, the catalog may reflect the data set's 
extent on the second volume, whereas there is no longer an 
extent on the second volume. Prior to issuing a RESETCAT 
command, you should restore compatible levels of volumes 
containing mult i volume data sets. RESETCAT would then be issued 
to reset the catalog to reflect the restored level of all data 
sets on all reset volumes. 

If, in the above example, the second volume was restored and 
RESETCAT specified only that volume as a reset volume, the 
entry-sequenced data set may be marked unusable for that volume 
and the space allocated to it would be either scratched or 
returned to the catalog for suballocat i on . The primary 
description is on the first volume, which was not indicated as 
one to reset. The description of the data set used would be the 
description that currently resides in the catalog. If the data 
set is defined differently on the second volume (for example, 
extents do not match), the data set is marked unusable for that 
volume and the allocated space marked free. 

For a multivolume entry sequenced data set, a multivolume 
key-sequenced data set, or an alternate index defined on a 
volume different from the data set it is based on, minimizing 
the intersection of different multivolume data sets on a common 
volume will permit better use of RESETCAT. 

When all volumes of a multivolume VSAM data set or structure are 
not specified in the RESETCAT operation, the extent of checking 
depends on whether the primary CRA volume is specified for 
reset. If the primary CRA volume is specified for reset, all 
information in the catalog is replaced for the data set 
concerned. For all volumes of the multivolume data set, whether 
specified or not, the following consistency checks are made by 
RESETCAT: 

• Check the current catalog (if the volume is not specified) 
or the CRA (if the volume is specified) to ensure that the 
data set is def i ned on the volume. 

• Check the data set specified on each volume. Was it defined 
at the same time as the one specified in the. primary CRA? 

• Check the extents described on the volumes. Are they still 
allocated to the multivolume VSAM data set? 

Although the above checks guarantee that the catalog physically 
describes a data set correctly, these checks cannot guarantee 
that the level of data in the data set is at a consistent level. 
For instance, if a multivolume keyed-sequential data set was 
defined with the data on one volume and the index on another, 
the same Define-time would be associated with both. If, over 
some time, several additions, deletions, and updates were made 
without causing an extension of the data set, RESETCAT would be 
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unable to distinguish among different combination of volumes 
taken from this time period. Since the index contains direct 
VSAM pointers to the data, an inconsistent combination may cause 
errors. 

If the primary CRA volume is not specified for reset, the scope 
of checking is limited to volumes specified in the reset. The 
current catalog is checked to ensure that the current catalog 
entry describes the part of the data set on the reset volume. 
Hence, only verification (no reset) occurs for these partial 
entries. The check ensures that the part of the data set on the 
reset volume resides on the same physical place as described in 
the current catalog and is part of the same definition as the 
data set described in the current catalog. RESETCAT cannot 
guarantee that the level of data in the data set i s at a 
consistent level among different volumes. 



JCL REQUIREMENTS 



For the catalogs required during RESETCAT processing, the 
catalog being reset (indicated by the CATALOG parameter of the 
RESETCAT command) must appear in a STEPCAT or JOBCAT DD 
statement. The catalog in which the work file is defined 
(optionally indicated by the WORKCAT parameter) must appear in a 
STEPCAT or JOBCAT DD statement. If the WORKCAT parameter is not 
specified, the work file will be defined in the catalog 
specified in the first concatenation of the STEPCAT or JOBCAT DD 
statement . 

The relationship of the STEPCAT or JOBCAT DD statement is 
summarized below : 

1. If you want the work file defined in a catalog other than 
the master catalog, then that catalog must be specified 
first in the JOBCAT or STEPCAT DD statement concatenation. 

//STEPCAT DD DSN=workcat , DISP=SHR 
// DD DSN=resetcat,DISP=SHR 

The above example specifies the work file catalog and reset 
catalog, respectively, in the JOBCAT or STEPCAT DD statement 
for case ( 1 ) . 

2. If you want the work file defined in the master catalog, 
then the master catalog must be specified by name via the 
WORKCAT parameter and, if specified in the STEPCAT or JOBCAT 
DD statement, must appear last in the concatenation 
sequence. 

//STEPCAT DD DSN=resetcat , DISP=SHR 
// DD DSN=mastcat,DISP=SHR 

The above example specifies the reset catalog and master 
catalog, respectively, in the JOBCAT or STEPCAT DD statement 
for case (2) . 

Further, the catalog being reset must be used by the RESETCAT 
command as a data set. A separate DD statement may be used for 
this catalog. It should specify only the catalog being reset and 
should not be concatenated to another catalog. For example- 

//DDCAT DD DSN=catname,DISP=OLD 

DISP=0LD should be specified to ensure exclusive use of the 
catalog. If no DD statement is supplied, it will be dynamically 
allocated. 

For CRAs, a single DD statement is required for each volume 
containing a CRA if CRAFILES parameter of the RESETCAT command 
is specified. For example^ 

//DDCRA1 DD UNIT=3330,VOL=SER=XYZ,DISP=SHR 
//DDCRA2 DD UNIT=2314, VOL=SER=ABC, DISP=SHR 
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Unit affinity may be specified to reduce unit requirements. No 
two CRAs will be demanded concurrently by RESETCAT. 

For the work file, RESETCAT command requires a list of one or 
more volumes to define a temporary VSAM data set; no more than 
five volumes may be specified. If no data-set name is provided, 
a system-generated data set name will be used. The following is 
an example of a work file DD statement* 

//FILEW DD DSN=A.WFILE,UNIT=(3330,2),VOL=SER=(X,Y), 
// DISP=OLD,AMP='AMORG' 
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COPYING AND PRINTING 



The REPRO and PRINT commands ar& used to copy and print VSAM and 
nonVSAM data sets, and to copy VSAM catalogs. 



COPYING DATA SETS 



You use the REPRO command to do any of the following- 
Copy a VSAM data set into another VSAM data set. 
Copy a sequential data set into another sequential data set. 

Copy an alternate index as though it were a key-sequenced 
VSAM data set. 

Copy a SAM, ISAM, or VSAM data set (whose records are 
fixed-length) into an empty VSAM relative-record data set. 

Convert a sequential or i ndexed-sequential data set into a 
VSAM data set. 

Convert a VSAM or i ndexed-sequent i al data set into a 
sequential data set. 

Copy a data set — other than a catalog — to reorganize it. 
Data set reorganization is an automatic feature. 

Copy a nonrecoverable catalog from one volume to another, 
for example, from a 2314 volume to a 3330 volume. 

Make a backup copy of a catalog. 

Reload a backup copy of a catalog. 

Merge two VSAM data sets. 

Throughout the remainder of the REPRO discussion, all of these 
functions will be referred to as copying. 

Refer to the chapter "Command Format" for a description of the 
command format for REPRO. Several examples ar& included. 

VSAM data sets used as either input or output must be cataloged. 
Sequential and i ndexed-sequenti al data sets need not be 
cataloged. 

If a sequential or i ndexed-sequent i al data set is not cataloged, 
you must include the appropriate volume and unit parameters on 
your DD statement. You must also supply a minimum set of DCB 
parameters when the input data set is sequential or 
i ndexed-sequent ial , and/or output data set is sequential. The 
following table shows the four key parameters. 

Parameters Must Be Supplied by User Default If Not Supplied 



DSORG 
RECFM 
BLKSIZE 
LRECL 



IS 

F, FB, V, VB 

blocksi ze 

lrecl 



PS 

U 

None 

BLKSIZE for F or FB 

BLKSIZE-4 for V or VB 
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Note that the one parameter that is not supplied by default is 
BLKSIZE; you must supply this value. The DCB parameter DSORG 
must be supplied via the DD statement. The DCB parameters RECFM, 
BLKSIZE, and LRECL can be supplied via the DSCB or header label 
of a standard labeled tape; otherwise, they must be supplied via 
the DD statement. 

For a variable record length VSAM data set, the VSAM RDF — a 
4-byte field defining the record length — is not included in the 
VSAM record length. Thus, when REPRO attempts to copy a VSAM 
record whose length is within 4 bytes of MACRECL, a recoverable 
error occurs and the record is not copied. 

Access Method Services does not support records greater than 
32,760 bytes for nonVSAM data sets (that is, LRECL=X is not 
supported). If the logical-record length of a nonVSAM input data 
set is greater than 32,760 bytes, or, if a VSAM data set defined 
with a record length greater than 32,760 is to be copied to a 
sequential data set, your REPRO command will terminate with an 
error message. 

Records in an i ndexed-sequent i al data set that have a 
fixed-length, unblocked format with a relative-key-position 
(RKP) of zero are preceded by the key string when used as input. 
Therefore, the records in the output data set must have a record 
length defined that includes the extended length caused by the 
key string. Also, to copy "dummy" i ndexed-sequent ial records 
(records with hexadecimal T FF' in the first byte) you must 
specify the DUMMY option in the ENVIRONMENT parameter. 

Because data is copied as single logical records in either key 
order or physical order, automatic reorganization takes place. 
The reorganization can cause any of the following: 

• Physical relocation of logical records 

• Alteration of a record's physical position within the data 
set 

• Redistribution of free space throughout the data set 

• Reconstruction of the VSAM indexes 

Figure 7 describes how the records from the input data set are 

added to the output data set when the output data set is an 

empty or nonempty entry-sequenced, key-sequenced, sequential 
data set, or relative-record data set. 
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Empty Non-Empty 

Entry-Sequenced/ Creates new data set Adds records in sequential 
Sequential in sequential order. order to the end of the 

data set. (DISP=M0D must 
be specified for SAM 
sequenti al . ) 

Key-Sequenced Creates new data set Merges records by key and 

in key sequence and updates the index. Records 
builds an index. whose key duplicates a key 

in the output data set are 
lost, unless you specify the 
REPLACE option. 

Relative-Record Creates a new data set Records from another 

in relative-record relative-record data set are 
sequence, beginning merged, keeping their old 
with 1. record numbers. A new record 

whose number duplicates an 
existing record number is 
lost, unless you specify the 
REPLACE option. Records from 
any other type of organization 
cannot be copied into a nonempty 
relative-record data set. 

Figure 7. Adding Records To Various Types of Output Data Sets 



Note*- The copy operation is terminated if* 

• One physical I/O error is encountered while writing to the 
output data set, or 

• A total of four errors are encountered in any combination of 
the f ollowi ng : 

Logical error while writing to the output data set 

Logical error while reading the input data set 

Physical error while reading the input data set 

When copying to a key-sequenced data set, the records to be 
copied must be in ascending order with no duplicates (within the 
input data set). With an entry-sequenced data set, the records 
to be copied can be in any order. 

REPRO causes Access Method Services to retrieve record numbers 
from a sequential, i ndexed-sequent i al , or VSAM data set and 
store them in VSAM format in key sequence, record-number 
sequence, or entry sequence, or store them in a sequential data 
set. When records are stored in key sequence, index entries are 
created and loaded into an index component as control intervals 
and control areas are filled up. Free space, as indicated in the 
data-set definition in the catalog, is left, and records are 
stored on particular volumes according to key ranges, if 
indicated in the definition. 

You can load all of the records in one job or load them in 
several jobs. In subsequent jobs VSAM continues to store records 
as before, extending the data set as required. 

To use your own program to load a key-sequenced data set, first 
sort the records (or build them) in key sequence, and store them 
with sequential access (the PUT macro). Sea OS/VS Virtual 
Storage Access Method (VSAM) Programmer's Guide to find out how 
to use the VSAM macros to write your own program to load records 
into a data set. 
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COPYING A CATALOG 



The v REPRO command can be used to copy a catalog from one volume 
to another. When using REPRO to copy a catalog, both the input 
and the output objects must be catalogs (that is, you must first 
define a catalog on the device that is to contain the 
newly-copied catalog). A catalog might be copied to move it to a 
faster device type or to optimize the catalog's allocation. 

The receiving catalog need not be of the same device type as the 
source catalog. The receiving catalog must be empty. That is, 
the receiving catalog cannot contain any entries other than the 
entries that describe the catalog and its data space. 



You cannot copy the contents of a nonre 
recoverable catalog, and vice versa, no 
recoverable catalog into a recoverable 
nonrecoverable catalog into a recoverab 
export each VSAM data set (from the non 
then import it into the newly defined ( 
convert a recoverable catalog into a no 
to copy a recoverable catalog into a re 
can either export each VSAM data set fr 
then import it into the target catalog 
EXPORTRA/IMPQRTRA commands to accompli s 
volume basi s. 



coverable catalog into a 
r can you copy a 
catalog. To convert a 
le catalog, you must 
recoverable catalog), 
recoverable) catalog. To 
nrecoverable catalog or 
coverable catalog, you 
om the source catalog and 
or use the 
h the same thing on a 



If the specified input and output catalogs are the same catalog, 
the free chain rebuild in-place function is performed. This is 
the only function performed in this case. All DD cards referring 
to the catalog, including the JOBCAT/STEPCAT, must have DISP=SHR 
coded for this function. In addition, the rebuild function 
requires the INFILE(ddname)/OUTFILE(ddname) form of REPRO. The 
INDATASET/OUTDATASET (dynamic allocation) form of REPRO may not 
be used. 

The free chain rebuild in-place function is allowed for both 
recoverable and nonrecoverable catalogs. 

To use the REPRO command to copy a catalog, Access Method 
Services must be authorized. See "Authorized Program Facility 
(APF)" in QS/VS2 System Programming Library' Supervisor for 
information about program authorization. 



COPY-CATALOG PREPARATION 



In preparation for copying a catalog, you should determine the 
amount of space to be allocated in the receiving catalog. Part 
of the process of determining how to allocate space for the 
receiving catalog includes reviewing how space is allocated in 
the catalog to be copied. 



There is no method (besides dumping the c 
you to determine the size of the catalog' 
range. You can however, determine the siz 
data records) of the low-key range. (When 
and include DATA(RECORDS . . . ) , the number 
i s the number of data records you want th 
contain, unless you also specify an amoun 
subparameter of INDEX.) One of the catalo 
records (in the low-key range) is called 
record, or CCR. The CCR describes the fre 
intervals in the catalog, and contains st 
catalog is used. To print the CCR, issue 
shown below), specifying the name of the 
data set. 



atalog) that enables 
s index set or high-key 
e (that is, number of 
you define a catalog 
of records you specify 
e low-key range to 
t of space as a 
g's self-describing 
the catalog-control 
e (or unused) control 
atistics about how the 
the PRINT command (as 
catalog as the input 



PRINT INDATASET(catname) 
SKIP(3) - 
COUNT(l) 
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When catname identifies a user catalog, your job must include a 
JOBCAT or STEPCAT DD statement to describe and allocate the 
catalog. 

The CCR is printed in the "dump" format (an example of this 
format is included with the first example in "PRINT Examples"). 
The record's first 44 bytes are its key value. The next byte is 
the character "L," which identifies the record as a CCR-type 
record. The next nine bytes are three 3-byte fields whose 
hexadecimal values specify* 



Displacement 

45 CX'2D T ) 

48 (X'30') 
51 (X'33») 



Symbol Contents 

A The highest control interval number that 
can be assigned. 

B The next control interval number to be 
assi gned. 

C The number of deleted records (that is, 
the number of control intervals that are 
unused because the entry they contained 
was deleted) . 

To determine the number of records in the low-key range, you 
also need information contained in the catalog's data-component 
record in addition to the information contained in the CCR. To 
list the data-component record, issue the LISTCAT command as 
shown below : 

LISTCAT ENTRIES(catname)ALL 

Your job must include a JOBCAT or STEPCAT DD statement to 
describe and allocate the catalog. The name of the catalog's 
data-component record is shown in the listing as 
VSAM. CAT ALOG.BASE.DAT A. RECORD. 

The number of records in the catalog is the same as the number 
of control intervals in the low-key range that currently contain 
either catalog records (both base and extension records) or free 
records. The formula to derive the number of records varies 
depending on whether the low-key range has only one extent or 
has more than one extent. Using the LISTCAT output, find the 
VOLUME group for the low-key range of the data component. This 
is the information listed under the VOLUME heading where the 
LOW-KEY is shown as 00 and the HIGH-KEY is shown as 3F. Extents 
are shown under the EXTENTS heading for this VOLUME group. By 
looking at the EXTENTS information you can determine whether the 
low-key range has one or more than one extent. 

1. If the low-key range has one extent, the value of B obtained 
from the CCR is the number of records to use. 

2. If the low-key range has more than one extent, use the 
formulas shown below to obtain the number of records* 

a. For all low-key range extents except the last* 

((HIGH-RBA + 1) - LOW-RBA) / 512 

b. For the last extent* 

((B x 512) - LOW-RBA) / 512 



where* 

HIGH-RBA and LOW-RBA are the values obtained from the 
LISTCAT output for each extent, and B is the value 
obtained from the CCR. 

The sum of each a plus b, above, is the number of records to 
use. 
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To the number of records derived from either 1 or 2 above, you 
should add the constant 19. This will allow for the fifteen 
self-describing records of the target catalog plus the four free 
records which are always reserved for VSAM catalog use at the 
end of the low-key range. The final result should be specified 
as the value for primary when you specify: 

DATACRECORDSCprimaryCb secondary])) 



on your DEFINE USERCATALOG command. 
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When you specify the space allocation for the receiving catalog 
in terms of RECORDS as described above, you are defining the 
smallest possible receiving catalog. The value contained in the 
CCR field described as C above of the source catalog will 
determine how many free records will exist in the receiving 
catalog. These records will be available to hold new entries. 

The symbols A, B, and C have no meaning except in the formulas 
described above, which yield the number of control intervals 
that contain catalog records in the low-keyrange. The complete 
format of the CCR record is included in Virtual Storage Access 
Method (VSAM) for 0S/VS2 MVS ; Catalog Management Logic . See 
Planning for Enhanced VSAM Under OS/VS for more details about 
the catalog's structure and the low-key range. 



COPY-CATALOG PROCEDURE 



The following steps should be followed to copy a catalogs 

1. Use the DEFINE command to define a catalog into which the 
source catalog is to be copied. The preceding section 
describes a method of determining in records the smallest 
possible receiving catalog. 

The receiving catalog need not be of the same device type as 
the source catalog. The receiving catalog must be empty. 
That is, the receiving catalog cannot contain any entries 
other than the entries that describe the catalog and its 
data space. 

2. Use the REPRO command to copy the source catalog to the 
receiving catalog. You cannot specify any of the REPRO 
command's delimiters (FROMKEY, TOKEY, SKIP, or COUNT) when 
you use REPRO to copy a catalog. A concatenated JOBCAT or 
STEPCAT DD statement is required to describe and allocate 
both the source and receiving catalogs. When the master 
catalog is being copied (that is* the source is the master 
catalog), use a single JOBCAT or STEPCAT DD statement to 
describe and allocate the receiving catalog. (A DD statement 
is not required to describe and allocate the master (source) 
catalog. If a DD statement is included, an error message 
will result.) 

3. Use the EXPORT command to disconnect the source user catalog 
from the master catalog. This step is not necessary if the 
source catalog is the master catalog. 
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If the source catalog was a user catalog, you should take 
care to list the aliases of the user catalog in the master 
catalog before you issue the EXPORT command. You can use the 
LISTCAT command to list the aliases 5 

LISTCAT - 

CATALOG I ma stercat name/password) - 

ENTRIESCusercatname) - 

ALL 

The user catalog's aliases are listed under the heading 
"ASSOCIATIONS." 

If you use the IMPORT command to make the catalog available 
to another system, you can issue the DEFINE ALIAS command to 
reestablish each of the catalog's aliases. 

4. If the source catalog was a user catalog, use the DEFINE 
ALIAS command to establish the required aliases of the 
receiving catalog. 

5. Use the DELETE command to remove the source catalog from the 
receiving volume. The source catalog appears in the 
receiving catalog as a cluster as a result of the copy 
operati on. 

The DELETE CLUSTER to remove the source catalog records from the 
receiving catalog is a special form of DELETE. It results in the 
f ollowi ng : 

• The source catalog records are deleted from the target 
catalog. 

• The source catalog's Format-1 DSCB is changed to a 
suballocable data space. 

• The volume that contained the source catalog is now owned by 
the receiving (target) catalog. 

After this delete, the source catalog no longer exists. If you 
do not want the new catalog to own the source catalog volume, 
use DELETE SPACE for that volume to remove volume ownership from 
the new catalog. 

The copy-catalog procedure should be performed with caution. 
Until the source catalog is disconnected from the master 
catalog, two catalogs are available for use. 

At the completion of the copy-catalog procedure: 

• The DSCB on the source-catalog volume is modified so that it 
no longer indicates that the volume contains a catalog (step 
5). 

• A volume entry is created in the receiving catalog for the 
source-catalog volume; the source-catalog volume is owned by 
the receiving catalog (step 2). 

• Space used by the source catalog is made available for 
suballocati on (step 5). 

If you are copying the master catalog, special care should be 
taken that the job is executed when the system is otherwise 
quiesced. Otherwise, it is possible that updates could be made 
to the master catalog during the copy. To use the target catalog 
as a master catalog, the following steps should be taken 
following step 2 described above : 

• Replace the SYSCATLG member in SYS1. NUCLEUS (now cataloged 
in the target master catalog) so that the SYSCATLG member 
points to the new master catalog ("Appendix G. Changing the 
Attributes of the VSAM Master Catalog" gives an example of 
how to replace SYSCATLG). 
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RelPL the system. With the SYSCATLG member changed, the IPL 
will reference the new master catalog. 

Proceed with step 5 described above. 



BACKING UP A CATALOG 



You can use the REPRO command to unload a VSAM catalog into a 
key-sequenced, entry-sequenced, or sequential (SAM) data set. If 
the catalog becomes inaccessible, you can redefine the catalog 
and use REPRO to reload the backup to replace it. If the catalog 
is accessible, you can use REPRO to reload the backup and 
reestablish catalog entries. Reloading a catalog should be done 
judiciously since it is difficult to recover VSAM data spaces, 
page spaces, and data sets that have extended after a backup 
copy of the catalog was made. 

Using REPRO to unload or reload a password-protected catalog 
requires the catalog's master password. 

The parameters that limit the extent of copying are invalid for 
unload/reload. Parameters that indicate action on the output 
data set are also invalid. These parameters are s COUNT, FROMKEY, 
FROMNUMBER, FROMADDRESS, SKIP, TOKEY, TOADDRESS, TONUMBER, REUSE 
and REPLACE. 

Use a STEPCAT DD statement to identify the catalog that you are 
loading or reloading. 

Do not allow the catalog to be updated during the operation. 
(REPRO does not itself prevent other processing of the catalog.) 

To use the REPRO command to unload or reload a catalog, Access 
Method Services must be authorized. See "Authorized Program 
Facility (APF)" in QS/VS2 System Programming Library? Supervisor 
for information about program authorization. 



UNLOADING A CATALOG 



A sequential, key-sequenced, or entry-sequenced backup copy of a 
catalog is inaccessible as a catalog. Because there is little 
advantage in having the backup on a direct-access volume, you 
can most conveniently use magnetic tape to copy a catalog in a 
sequential data set. 

To unload a catalog into a key-sequenced or entry-sequenced data 
set, first define the data set in another catalog (for 
protect i on) . 

To continually have a recent backup copy available, you should 
unload a catalog periodically. With tape, you can easily 
alternate two or more volumes for several levels of backup. 

Use LISTCAT before unloading a catalog. You can compare the 
listing with the one you obtain after reloading. If you are 
unloading a recoverable catalog, use LISTCRA with the COMPARE 
option to ensure that the catalog and its volumes are 
synchronized at the time of the unload operation. 

Example 3 in the section "REPRO Examples" describes the DCB 
parameters you must specify on your DD statement if you unload 
your catalog to a nonVSAM sequential (SAM) data set. 
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RELOADING A CATALOG 



You must use REPRO to reload the backup copy into a catalog (the 
"target") with the sarqe name, volume-serial number, and device 
type as the original catalog. Reloading the master catalog has 
special requirements (for details, see the section "Backing Up 
the Master Catalog" in the chapter "Data Security and 
Protect i on.") 
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Reloading a version of the original catalog results in a catalog 
equivalent to the original one at the time the backup was made. 
Reloading replaces entries in the target catalog with entries of 
the same name in the backup. It inserts into the target entries 
that exist only in the backup. It deletes from the target 
entries that exist only in the target. During reloading, Access 
Method Services issues a maximum of one hundred messages to 
indicate entries that exist only in the target or only in the 
backup. 
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Note: LISTCAT cannot run in a job step in which the catalog is 
empty when opened. To ensure that the LISTCAT correctly reflects 
the contents of the catalog, it is recommended that it be run as 
a separate job step. 

After you reload a catalog, use LISTCAT to list its contents. 
Run LISTCAT in a separate job step, so that the catalog will be 
closed after it is reloaded (to update its self-defining 
information). To ensure that you have used the right backup, 
compare the listing with the one you obtained before unloading 
the original catalog. 

Reloading or restoring a recoverable catalog does not cause the 
catalog recovery area to be updated. Therefore, the LISTCRA 
command with COMPARE option should be run to identify mismatches 
between the catalog and the catalog recovery area (CRA). (This 
should be done in a separate job step, immediately after the 
reload.) These mismatches should be resolved as necessary before 
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the catalog can be used. (See the section "Catalog Recovery" in 
the "Data Security and Protection" chapter.) No other jobs 
should be run after the reload and before the LISTCRA if these 
jobs access any of the data sets cataloged in the reloaded 
catalog. 

If VSAM data sets or data spaces have been deleted or 
permanently exported since the last catalog backup and the 
catalog is reloaded or restored, then the deleted data sets or 
data spaces will still be defined in the restored catalog. Any 
attempt to process these. entri es will yield unpredictable 
results because the space reflected in the catalog may no longer 
be owned by the catalog. The catalog may be corrected by 
reissuing the DELETE commands. 

If VSAM data sets or data spaces have been defined or imported 
since the last catalog backup and the catalog is reloaded or 
restored, then the defined data sets or data spaces will not be 
defined in the reloaded or restored catalog. Processing these 
data sets or data spaces by means of the restored catalog is not 
possible since they cannot be accessed. The space formerly 
occupied by these VSAM data sets or data spaces will not be 
usable, but may be recovered by scratching the format-1 DSCBs in 
the VTOC for the data spaces. If any volumes were added to the 
catalog (between the backup and the recovery), they will also be 
unusable until you use the DELETE command with FORCE option or 
ALTER REMOVEVOLUMES to give up volume ownership. 

If a VSAM data set has been extended since the last catalog 
backup, the new extents will not be defined in the restored or 
reloaded catalog. Any attempt to process records in the added 
extents will result in a logical error. If the data set has been 
extended within space already allocated to the data set before 
the backup but has acquired no new extents, then you can issue 
the VERIFY command to update the catalog pointers, and the data 
set may be accessed normally. 

The data in any extents that have been acquired by the data set 
since the catalog was backed up is unrecoverable. For an 
entry-sequenced data set the data in any new extents should 
consist only of records that have been added to the end of the 
data set. Therefore, it is possible to recover all of the data 
in the old extents by accessing the data set sequentially up to 
the end of the old physical space allocation. For a 
key-sequenced data set, the new extents may be any portion of 
the data set because of control-area splits. An attempt to read 
the data in logical sequence will fail with an invalid RBA 
indication when the data in the new extents is reached. You 
could access the key-sequenced data set by means of address 
sequence, but you then have the problem of identifying the 
missing records. Individual data set recovery for those data 
sets affected will be necessary. 

See the section "Updating a Backup Catalog" in the chapter "Data 
Security and Protection" for a discussion of making the contents 
of the backup catalog agree with the contents of the original 
catalog at the time it became inaccessible. 



OPTIMIZING THE PERFORMANCE OF UNLOAD/RELOAD 



You can specify additional I/O buffers for unloading and 
reloading by using* 

• The AMP parameter in the STEPCAT DD statement that 
identifies the catalog — AMP= 'BUFND=x, BUFNI=2», where x 
equals 2 times the number of 512-byte control intervals p&r 
track of the device used for the catalog. 

• The AMP parameter in the DD statement that identifies a 
key-sequenced or entry-sequenced backup copy — AMP= , BUFND=x> 
BUFNI=2*, where x equals 2 times the number of 512-byte 
control intervals p&r track of the device used for the 
backup. 
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The DCB parameter in the DD statement that identifies a 
sequential backup copy — DCB=BUFNO=x, where x equals either^ 

2 times the number of 512-byte control intervals per 
track of the device used for the catalog (when the 
backup is on magnetic tape) or 

2 times the number of physical records per track of the 
device used for the backup (when the backup i s on a 
direct-access volume). 

Block the records in a sequential backup data set. Some 
catalog records are 47 bytes long; the rest lare 505 bytes 
long. Use DCB=RECFM=VB . 



PRINTING DATA SETS 



You use the PRINT command to list part or all of a 
key-sequenced, relative-record, or entry-sequenced VSAM data 
set, an alternate index, a VSAM catalog, or a nonVSAM data set. 
The components of a key-sequenced data set or alternate index 
can be listed individually. To list a component of a 
key-sequenced data set or alternate index, specify the component 
name as the data set name. An alternate index is printed as 
though it were a key-sequenced cluster. 

If a sequential or i ndexed-sequent i al data set i s" not cataloged, 
you must include the appropriate volume and unit parameters on 
your DD statements. 

You must also supply a minimum set of DCB parameters when the 
data set to be printed is sequential or i ndexed-sequenti al . The 
following table shows the four key parameters: 

Parameters Must Be Supplied By User Default If Not Supplied 

DSORG IS PS 

RECFM F, FB, V, VB U 

BLKSIZE blocksize None 

LRECL lrecl BLKSIZE for F or FB 

BLKSIZE-4 for V or VB 

Note that the one parameter which is not supplied by default is 
BLKSIZE; you must supply this value. The DCB parameters can be 
supplied via the DSCB or header label of a standard labeled 
tape; otherwise, they must be supplied via the DD statement. 

Access Method Services does not support records greater than 
32,760 bytes for nonVSAM data sets (that is, LRECL=X is not 
supported). If the logical record length of a nonVSAM input data 
set is greater than 32,760 bytes, your PRINT command will 
terminate with an error message. 

Sequential and entry-sequenced data sets are listed in physical 
sequential order. Indexed-sequent i al and key-sequenced data sets 
can be listed in key order or in physical sequential order. A 
base cluster can be listed in alternate-key sequence by 
specifying a path name as the data-set name for the cluster. 

Only the data content of logical records is listed. System 
defined control fields are not listed. Each record listed is 
identified by one of the following: 

• Its relative byte address (RBA) for entry-sequenced data 
sets. 

♦ Its key for i ndexed-sequenti al (ISAM) and key-sequenced data 
sets, and for alternate indexes. 
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• Its sequential record number for sequential (nonVSAM) and 
relative-record data sets. 

Note: if four logical and/or physical errors sre encountered 
while trying to- read the input, the printing is terminated. 

To use the PRINT command to print a VSAM catalog, Access Method 
Services must be authorized. See "Authorized Program Facility 
(APF)" in 0S/VS2 System Programming Library* Supervisor for 
information about program authorization. 

Refer to the chapter "Command Format" for a description of the 
command format for PRINT. Examples of the PRINT command sr& 
included. 
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LISTING TAPE VOLUMES MOUNTED AT CHECKPOINT 



OS/VS Checkpoint/Restart explains taking checkpoints and 
restarting programs. Here is a summary 5 

During processing* a program can issue the^ CHKPT macro to record 
various information for use in restarting the processing if an 
error prevents the program from continuing. Recording 
information by way of CHKPT is called taking a checkpoint. The 
records that contain the information make up a checkpoint entry 
in the checkpoint data set, which contains a~n entry for each 
checkpoint that is taken. 

The checkpoint data set can be a sequential data set or a 
partitioned data set. In a partitioned data set, each checkpoint 
entry is a member of it. 

Checkpoint information includes the volume serial numbers of 
tape data sets that were open at the checkpoint. The CHKLIST 
command enables you to list these volume serial numbers to 
identify the tape data sets that need to be mounted for restart. 

For a checkpoint data set with DS0RG=PS (sequential data set), 
you can select one or more specific checkpoint entries for which 
the tape information is to be listed by a single CHKLIST 
command. By not selecting any specific entry, all checkpoint 
entries will be processed. 

You can use CHKLIST to process a checkpoint data set with 
DS0RG=P0 (partitioned data set) in the following manner 1 

• Specify DSNAME=dsname(member) on the JCL statement that 
defines the checkpoint data set. 

• Do not select a specific checkpoint entry, so that the 
single entry specified by member after dsname will be 
processed. 

The CHKLIST command causes the following information to be 
listed: 

• The checkpoint identifier for the entry being processed. 

• For each tape data set that was open at the time of the 
checkpoint, the following items are listed: 

dsname 

DD name 

type of unit on which the volume was mounted 

the sequence number of the mounted volume 

volume serial numbers with an * by the volume serial 
number of the mounted volume. 

To process multiple members of a partitioned checkpoint data 
set, use the CHKLIST command once for each member. 

Note : The CHKLIST command cannot be invoked as a TSO command. 

Refer to the chapter "Command Format" for a description of the 
command format for CHKLIST. Examples of the CHKLIST command are> 
also included. 
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COMMAND FORMAT 



This chapter sets out the functional command formats. Parameters 
are grouped into categories such as name, data organi zati on , 
allocation* and protection and integrity. The format of each 
command is then shown, followed by a discussion of each 
parameter. Examples of each command follow the parameter 
di scussi on. 



FUNCTIONAL COMMAND FORMAT 



This section provides complete reference information about all 
functional commands of Access Method Services. The commands 
discussed in the section are: 

ALTER command, which is used to alter attributes of data 
sets and other objects that have already been defined. 

BLDINDEX command, which is used to build an alternate index 
over a base cluster. 

CHKLIST command, which lists tape data sets opened during a 
checkpoint. 

CNVTCAT command, which converts OS catalog entries to VSAM 
catalog entries and merges them into a VSAM catalog. 

DEFINE ALIAS command, which is used to define an alternate 
name for a nonVSAM data set or a user catalog. 

DEFINE ALTERNATEINDEX command, which is used to define an 
alternate index. 

DEFINE CLUSTER command, which is used to define a cluster 
for a key-sequenced, entry-sequenced, or relative-record 
data sets. 

DEFINE GENERATIONDATAGROUP command, which is used to create 
a catalog entry for a generation data group. 

DEFINE NONVSAM command, which is used to define a catalog 
entry for a nonVSAM data set. 

DEFINE PAGESPACE command, which is used to define an entry 
for a page space data set. 

DEFINE PATH command, which is used to define a path directly 
over a base cluster or a path over an alternate index and 
its related base cluster. 

DEFINE SPACE command, which is used to define a VSAM data 
space. 

DEFINE USERCATALOG command, which is used to define a VSAM 
user catalog. 

DELETE command, which is used to delete data sets and other 
objects, including catalogs and nonVSAM data sets. 

EXPORT command, which is used to export VSAM files and to 
disconnect user catalogs. 

EXPORTRA command, which is used to recover VSAM and nonVSAM 
catalog entries from catalog recovery areas and, for VSAM 
objects (clusters and alternate indexes), to recover the 
data itself by means of catalog recovery areas. 
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IMPORT command, which is used to import VSAM data sets and 
to connect user catalogs. 

IMPORTRA command, which is used to reconstruct multiple VSAM 
data sets from a data set created by the EXPORTRA command. 

LISTCAT command, which is used to list catalog entries. 

LISTCRA command, which is used to list or compare the 
contents of a given catalog recovery area. 

PRINT command, which is used to print both VSAM and nonVSAM 
data sets. 

REPRO command, which is used to copy and load both VSAM and 
nonVSAM files and VSAM catalogs. 

VERIFY command, which is used to verify and correct certain 
problems that have made your data set unusable. 

See "Notation Conventions" in the "Preface" (About This Book) 
for an explanation of the symbols used in the command formats. 
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ALTER 



The format of the ALTER command is 



ALTER 



en try name [/pa s sword 3 

[ADDVOLUMESlvolserCb volser. ..3)3 

[ATTEMPTS(number)3 

[AUTHORIZATIONCentrypointEb string3 )3 

[BUFFERSPACECsize)3 

IC0DE(code)3 

[CONTROLPWt password) 3 

[DESTAGEWAIT|N0DESTAGEWAIT3 

[EMPTYIN0EMPTY3 

CERASEIN0ERASE3 

[EXCEPTI0NEXIT(entrypoint)3 

CFILE(dname)3 

CFREESPACECCI-percentCb CA-percent3 )3 

[INHIBIT|UNINHIBIT3 

[KEYSUength b offset)3 

[MASTERPW(password)3 

[NEUMAME(newname)3 

[NULLIFY( 

[AUTHORIZATION (MODULE I STRING) 3 

[CODE3 

[C0NTR0LPW3 

[EXCEPTI0NEXIT3 

[MASTERPW3 

[OWNER 3 

[READPW3 

[RETENTI0N3 

[UPDATEPW3)3 
EOUNER(ownerid)3 
[READPWI password) 3 
[RECORDSIZEtaverage b maximum)3 
[REMOVEVOLUMESCvolserEb volser. ..3)3 
[SCRATCH I NOSCRATCH3 

[SHAREOPTIONStcrossregionEb crosssystem3 )3 
[STAGE | BIND | CYLINDERFAULT 3 
[T0(date)|F0Rtdays)3 
[UNIQUEKEY I N0NUNIQUEKEY3 
[UPDATE | NOUPDATE3 
[UPDATEPW( password ) 3 
[UPGRADE | NOUPGRADE3 
[ URITECHECK | N0URITECHECK3 

[CATAL0G(catname[/password3 )3 



ALTER Parameters: Summary 



The parameters of the ALTER command are described in the 
following groups: 

• Name, which describes the entryname and NEWNAME parameters. 
These parameters are used to name the entry to be altered 
and, optionally, to rename the entry. These parameters ar& 
also used to rename a member of a nonVSAM partitioned data 
set. 

• Protection and integrity, which describes the NULLIFY, 
MASTERPU, CONTROLPW, UPDATEPW, READPW, UNINHIBIT, INHIBIT, 
CODE, ATTEMPTS, AUTHORIZATION, EXCEPTIONEXIT, OWNER, TO, 
FOR, SHAREOPTIONS, ERASE, NOERASE, ERASE, NOERASE, 
WRITECHECK, NOWRITECHECK, DESTAGEWAIT, and NODESTAGEWAIT 
parameters. These parameters are used to alter protection 
and integrity attributes. 

• Allocation, which describes the FILE, FREESPACE, 
BUFFERSPACE, RECORDSIZE, KEYS, ADDVOLUMES, REMOVEVOLUMES, 
STAGE, BIND, and CYLINDERFAULT parameters. These parameters 
are used to modify the amount of free space to be left in 
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ALTER 

control intervals and control areas, to modify the amount of 
buffer space to be provided, to add and remove volumes from 
the list of volumes to be used as overflow volumes, and to 
modify the indication of how a data or index component that 
is stored on a mass-storage volume is to be staged. 

When a data set does not contain any data records, 
RECORDSIZE can be specified to modify the data set's average 
and maximum record sizes. When a key-sequenced data set or 
alternate index is empty, KEYS can respecify the the length 
and position of each. data-record' s key field. 

Alternate index and path, which describes the UNIQUEKEY, 
NONUNIQUEKEY, UPDATE, NOUPDATE, UPGRADE, and NOUPGRADE 
parameters. These parameters specify attributes that apply 
only to alternate index and path entries. 

Generation-data-group attributes, which describes the EMPTY, 
NOEMPTY, SCRATCH, and NOSCRATCH parameters. These parameters 
are used to alter what is to happen when the maximum number 
of generation data sets is reached. 

Catalog, which describes the CATALOG parameter. This 
parameter is used to name the catalog in which the entry to 
be altered is defined. 



Entry-Types That can Be Altered 



An "X" in Figure 8 indicates you can respecify the value or 
attribute for that type of VSAM catalog entry. Some attributes, 
when specified for a cluster or alternate index, apply to its 
data or index component entry only, and not to the cluster or 
alternate-index entry. Some attributes can only be specified for 
the cluster's or alternate-index's data or index component 
entry — you must identify the component's entry with its 
entryname. You can use the Access Method Services LISTCAT 
command to determine the names VSAM generated for the object's 
components. 

When you identify a group of entries with a generic name, 
entries whose entrynames match the supplied qualifiers are 
altered, if they contain the type of information specified with 
the ALTER command's other parameters. 
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Type of Catalog Entry: 



ALTERNATE INDEX 
DATA INDEX 



CLUSTER 
DATA 
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Figure 8 (Part 2 of 2). ALTER Parameters and the Entry-Types to Which Each 
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You cannot identify the following types of entries: alias 
entries* a catalog's data or index-component entries* and a 
mastei — catalog's self-describing entries. 
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ALTER PARAMETERS 



Required Parameters 



en trynameC /password 3 

is a required parameter that names the entry to be altered 
and supplies a password. See the section "Generic Names and 
ALTER" for a description of how to specify a generic name 
in order to alter multiple entries with one ALTER command. 

See "Modifying Catalog Information" if you wish to use data 
or index entryname or cluster entry subparameters. 

If you are renaming a member of a nonVSAM partitioned data 
set, the entryname must be specified in the format J 
pdsname(membername) . 

If you are altering a password-protected entry in a 
password-protected catalog, you must specify a password. 
The password can be specified with entryname or in the 
CATALOG parameter. For the following entry types, the 
password must be the master password for the entry or for 
the catalog that contains the entry: alternate index, 
cluster, page space, path, user catalog, data, and index. 
If a data or index component entry is to be altered, the 
master password of the cluster, component, or catalog can 
be supplied. For the following entry types, the password 
must be the update- or highei — level of the catalog that 
contains the entry : nonVSAM and GDG. 



Optional Parameters 



ADDVOLUMESCvolseKb volser]) 

specifies volumes to be added to the list of overflow 
(candidate) volumes. 

volser 

A volume serial number, volser, may contain 1 to 6 
alphameric, national (31, 8, and $), and special 
characters; the special characters include commas, 
blanks, semicolons, parentheses, slashes, asterisks, 
periods, quotation marks, ampersands, plus signs, 
hyphens, and equal signs. A volume serial number must 
be enclosed in single quotation marks if it contains a 
special character. Single quotation marks within a 
volume serial number must be coded as two single 
quotation marks. 

The volumes to be added as candidate volumes must already 
be owned by the catalog that contains the entry being 
altered; that is, space must have been defined on a volume 
to be added or the volume must have been identified as a 
candidate volume. 

Abbreviation: AVOL 

ATTEMPTS (number) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. If i s specified, the operator is not prompted 
and is not allowed to enter a password from the console. 
This parameter can be coded, but only has effect when the 
entry's master password is not null. A prompting message is 
issued only when the user has not already supplied the 
appropriate password. 

number 

is an integer from to 7 and can be expressed in 
decimal (n), hexadecimal (X'n f ), or binary (B'n') 
form. 
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Note to TSO users: At a TSO terminal/ the logon password is 
checked first before the user is prompted to supply a 
password. Checking the logon password counts as one attempt 
to obtain a password. If ATTEMPTS is not specified, the 
user has one attempt to supply the password because the 
default is 2. 

Abbreviation: ATT 

AUTHORIZATION(entrypoint[b string]) 

specifies that a usei — security-verification routine (USVR) 
is available for additional security verification. 

entrypoi nt 

specifies the name of the USVR. entrypoint can contain 
1 to 8 alphameric characters (A through Z, and 
through 9), or national characters (3>, #, $), and 
special characters (the hyphen (-) and the 12-0 
overpunch (X'C)). The name's first character is 
either an alphabetic character or a national 
character. 

string 

specifies information to be passed on to the USVR when 
it receives control to verify authorization, string 
can contain 1 to 255 EBCDIC characters. 

When the string contains a special character (that is, 
a comma [,], semicolon E;3, blank [b], period [.], 
single quote C'3, semicolon E;3, ampersand C&3, plus 
[+], equal sign [=], hyphen C-3, parenthesis C( or )3, 
slash [/], or asterisk C*3), enclose the string in 
single quotation marks (for example, 
AUTHORIZATION(entrypoint, 'KDORIS*')). 

When the string contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, AUTHORIZATION(entrypo i nt, ' *CA"R0L* ' ) ) . 

You can code string in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, AUTHORIZATION(entrypoi nt , X'E2E4C5') is 
the same as AUTHORIZATION(entrypoi nt , SUE). The string 
can contain up to 255 hexadecimal characters when 
expressed in this form, resulting in up to 128 bytes 
of information. 

Abbreviation: AUTH 

BUFFERSPACE(size) 

specifies the minimum space to be provided for buffers. The 
amount specified should be greater than or equal to the., 
amount specified in the original definition. If the amount 
is less than was specified when the entry was defined, VSAM 
attempts to get enough space to contain two data component 
control intervals and, if the data is key sequenced, one 
index component control interval. BUFFERSPACE can be 
specified only for a catalog, or for a cluster's or 
alternate-index's data component. 



si ze 



is the amount of space to be provided for buffers. If 
you are altering the bufferspace for a catalog, the 
decimal values you can specify are limited to 3072, 
4096, 5120, 6144, 7168, and 8192. 

size can be expressed in decimal (n), hexadecimal 
(X*n')> or binary (B'n*) form. If the size specified 
is less than the amount VSAM requires, VSAM gets the 
amount it requires when the data set is opened. 

Abbreviations: BUFSP or BUFSPC 
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CATALQG(catname[/password3 ) 

specifies the catalog location of the entry to be altered. 
See "Order of Catalog Use- ALTER" for information about the 
order in which catalogs are searched. 

catname 

specifies the name of the catalog that contains the 
entry. 

password 

specifies the master password of the catalog that 
contains the entry to be altered. If the entry to be 
altered is password protected and the catalog is also 
password protected, a password must be entered either 
through this parameter or through the parameter that 
specifies the entry to be altered. 

Abbreviation: CAT 

CODE(code) 

specifies a code name for the entry being altered. If an 
attempt is made to access a password-protected entry 
without a password/ the code name is used in a prompting 
message; the code enables the operator or TSO terminal user 
to be prompted for the password without disclosing the name 
of the entry. 

If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password, the operator or TSO terminal user is 
prompted with the name of the entry. 



code 

can contain 1 to 8 alphameric or special characters. 
When the code contains a special character (that is> a 
comma [,3, semicolon [;3, blank Cb3, period [.3, 
single quote t'3, ampersand C&3, plus sign [+3, equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash [/3, 
or asterisk C*3, enclose the code in single-quotation 
marks (for example, C0DE( » XDORIS* ' ) ) . 

If the code contains a lowercase alphabetic character, 
it will be folded to an uppercase alphabetic 
character. 

When the code contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, C0DE( ' *CA " ROL* » ) ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0DE(X' E2E4C5' ) is the 
same as CODE(SUE) . 

CONTROLPW(password) 

specifies a control password for the entry being altered. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb3, period C.3, 
single ['3, ampersand t&3, plus sign [+3, equal sign 
[=3, hyphen C-3, parenthesis C( or )3, slash C/3, or 
asterisk C*3, enclose the password in single-quotation 
marks (for example, C0NTR0LPW( 'XDORIS* ' ) ) . 
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When the password contains a special character and 
also contains a single-quotation mark/ code the 
imbedded quotation mark as two single-quotation marks 
(for example, CONTROLPWC '*CA " ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0NTR0LPW(X' E2E4C5' ) 
is the same as CONTROLPW(SUE) . 

Abbreviation: CTLPW 

DESTAGEWAIT | NODESTAGEWAIT 

specifies whether a data or index component that is stored 
on a mass-storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 
These parameters can be specified only for the data or 
index component of a cluster or alternate index. 

DESTAGEWAIT indicates that destaging is to be completed 
before control is returned from VSAM to the program that 
issues the CLOSE macro. VSAM can thus notify the program 
whether destaging was successful. 

NODESTAGEWAIT indicates that notification of unsuccessful 
destaging is to be made only by a message to the operator. 

Abbreviations: DSTGW and NDSTGW 

EMPTYINOEMPTY 

specifies what is to happen when the maximum number of 
generation data sets has been cataloged. EMPTY specifies 
that all of the generation data sets are to be uncataloged. 
NOEMPTY specifies that only the oldest generation data set 
is to be uncataloged. 

Abbreviations: EMP and NEMP 

ERASEINGERASE 

specifies whether the data component is to be erased when 
its entry in the catalog is deleted. If ERASE is specified, 
the component is overwritten with binary zeros when its 
catalog entry is deleted. 

Abbreviations: ERAS and NERAS 

EXCEPTIONEXIT(entrypoint) 

specifies the name of the usei — written routine that 
receives control when an exception (usually an I/O error) 
occurs while the entry's object is being processed. An 
exception is any condition that causes a SYNAD exit to be 
taken. The object's exception exit routine is processed 
first, then the user's SYNAD-exit routine receives control. 

You cannot specify this parameter to add an exception-exit 
routine to a VSAM cluster that is cataloged in a VSAM 
catalog created in an 0S/VS2-2 (or lower release level) 
system. 

Abbreviation: EEXT 

FILE(dname) 

specifies the name of a DD statement that describes the 
volume whose catalog recovery area contains the entry's 
copy. You can specify FILE when the entry to be altered is 
in a recoverable catalog. See the section "Restoring 
Catalog Entries After System Failure" for a description of 
catalog recovery area contents for each volume. The volume 
whose catalog recovery area contains a copy of the catalog 
entry must always be identified in the DD statement 
referenced via FILE. In addition* 
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• If you specify ADDVOLUMES or REMOVEVOLUMES, the 
volume(s) being added or removed must be identified. 

• If you specify NEWNAME for a nonVSAM data set or the 
data or index component of a unique cluster, alternate 
index, or page space which does not reside on the same 
volume as the catalog recovery area entry, that 
volume(s) must be identified. If FILE is not specified, 
the catalog recovery area volume(s) is dynamically 
allocated. It must be mounted as permanently resident 
or reserved. 

FILE can be used to specify the name of a DD statement 
that identifies the volume of an entry to be renamed if 
a nonVSAM data set or the data or index component of a 
unique cluster, alternate index, or page space is to be 
renamed. If FILE is not specified, the object's volume 
is dynamically allocated. The object's volume must be 
mounted as permanently resident or reserved. 

FILE can be used to identify the name of the 
partitioned data set if a member is to be renamed. If 
FILE is not specified, the partitioned data set is 
dynamically allocated. 

If multiple volumes of different device types are to be 
identified via FILE, you must use concatenated DD 
statements. 

FREESPACE(CI-percentCb CA-percent3) 

specifies the amount of space that i s to be left free after 
any allocation and after any split of control intervals 
(Cl-percent) and control areas (CA-percent ) . 

The amounts are specified as percentages. The percentages, 
which must be equal to or less than 100, may be expressed 
in decimal, hexadecimal, or binary. If you specify 100 
percent of free space, one record is placed in each control 
interval and one control interval is placed in each control 
area . 

Cl-percent and CA-percent can be expressed in decimal Cn), 
hexadecimal CX'n'), or binary (B'n') form. 

Abbreviation: FSPC 

INHIBIT | UNINHIBIT 

specifies whether the entry being altered can be accessed 
for any operation or for only read operations. INHIBIT 
specifies that the entry being altered is only to be read. 
UNINHIBIT specifies that the read-only restriction set by a 
previous ALTER or EXPORT command is to be removed. 

Abbreviations: INH and UNINH 

KEYSClength b offset) 

specifies the length and offset of the object's key. If the 
entry being altered defines an alternate index, offset 
applies to the alternate key in the data records in the 
base cluster. For more information, see entryname. 

Restrictions: Can be specified only if all of the following 
are true : 

• The object whose entry is being altered contains no 
data records. 

• The values for KEYS in the catalog must be default 
values. However, if nondefault keys are altered and the 
new value matches the old, processing continues for any 
other parameters specified on the command. For default 
values, see the DEFINE command that defines the object. 
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The key must fit within the record whose length is 
specified by the RECORDSIZE parameter. 

The key must fit in the first record segment of a 
spanned record. 

The new values for KEYS must not conflict with the 
control interval size specified when the object was 
def i ned. 

The object whose entry is being altered is an alternate 
index, a path, a key-sequenced cluster, or a data 
component of a key-sequenced cluster or alternate 



i ndex 
length 




MASTERPUC password) 

specifies a master password for the entry being altered. 

For more details about the object's master password, see 

the DEFINE command that defines the object. 

The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated 
with it. If MASTERPW is not specified, the highest level 
password specified becomes the password for all higher 
levels. The MASTERPW is not specified, the highest level 
password specified becomes the password for all higher 
levels. The master password allows all operations. 

password 

i s a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank [b3, period C.3, 
single quote C'3, ampersand C&3, plus sign [+], equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3, enclose the password in 
single-quotation marks (for example, 
MASTERPW('XDORISK')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, MASTERPW( * *CA ' ■ ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, MASTERPW(X' E2E4C5 ' ) is 
the same as NASTERPW( SUE) . 

Abbreviation: MRPW 

NEWNAMEC newname ) 

specifies that the entry to be altered is to be given a new 
name. 

The new name may contain 1 to 44 alphameric characters, (A 
through Z, and through 9), nationad characters O, #, and 
$), and two special characters (the hyphen and 12-0 
overpunch) . Names that contain more than eight characters 
must be segmented by periods; one- to eight characters may 
be specified between periods. The first character of any 
name or name segment must be either an alphabetic character 
or a national character. 
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If the object being renamed is a unique cluster or 
component? or a nonVSAM data set, the object's volume must 
be mounted because the volume's VTOC is modified. You can 
use a JCL DD statement (see the FILE parameter) to cause 
the object's volume(s) to be allocated. If you do not 
supply a DD statement, the object's volume(s) is 
dynamically allocated. The volume(s) must be mounted as 
either permanently resident or reserved. 

If you specify generic names, you specify both the 
entryname and the newname as generic names. See "Generic 
Names and ALTER" for details on generic names. 

If you are renaming a member of a nonVSAM partitioned data 
set, the newname must be specified in the format 1 
pdsname(membername) . 

If you are renaming a VSAM data set which is 
RACF-protected, the existing RACF data set profile will be 
renamed. If a data set profile already exists for the new 
data set name prior to the ALTER command, the command is 
terminated and the data set name and/or protection 
attributes remain unchanged. If the old profile cannot be 
found or cannot be altered to the NEWNAME, the NEWNAME 
action will not be completed in the catalog, and an error 
message will indicate the reason for noncomplet i on . 

Abbreviation: NEWNM 

NULLIFY 

specifies that the protection attributes identified by 
subparameters of NULLIFY are to be nullified. Attributes 
are nullified before any respeci f i cati on of attributes is 
performed. If all levels of passwords are nullified and 
none are respecified, CODE, AUTHORIZATION, and ATTEMPTS 
have no effect. 

Abbreviation: NULL 

AUTHORIZATIONCMODULE I STRING ) 

specifies that either the usei — authorization routine 
or the uset — authorization record is to be nullified. 
When MODULE is specified, the module name is removed 
from the catalog record, but the module itself is not 
deleted. If you nullify the usei — authorization module, 
the usei — authorization record (character string) is 
also nullified. When you nullify the authorization 
record, the corresponding module is not nullified. 



CODE 



Abbreviations: AUTH, MDLE, and STRG 



specifies that the code name used for prompting is to 
be nullified. 



CONTROLPW 

specifies that the control password is to be 
nullified. 

Abbreviation: CTLPW 

EXCEPTIONEXIT 

specifies that the entry's exception exit is to be 
nullified. The module name is removed from the catalog 
record, but the exception-exit routi ne i tself is not 
deleted. 

Abbreviation: EEXT 

MASTERPM 

specifies that the master password is to be nullified. 
If a new master password is not specified and if other 
passwords exist, the highest level password that 
exists automatically becomes the password for all 
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higher levels, including the master. 

Abbreviation: mrpw 

OWNER 

specifies that the owner identification is to be 
null i f i ed. 

READPU 

specifies that the read password is to be nullified. 

Abbreviation: RDPW 

RETENTION 

specifies that the retention period, specified in a TO 
or FOR parameter, is to be nullified. 

Abbreviation: RETN 

UPDATEPW 

specifies that the update password is to be nullified. 

Abbreviation: UPDPW 

OWNER(ownerid) 

specifies the identification of the owner of the entry 
being altered. 

owneri d 

can contain 1 to 8 EBCDIC characters. When the ownerid 
contains a special character (that is, a "comma [,], 
semicolon C;3, blank Cb], period [.], single quote 
C'3, ampersand C&3, plus sign [+3, equal sign C=3, 
hyphen C-3, parenthesis C( or )3, slash C/3, or 
asterisk C*3, enclose the ownerid in single-quotation 
marks (for example, 0WNER( ' KDORIS* ' ) . 

When the ownerid contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, 0WNER( • *CA ' ' ROL* * ) ) . 

You can code ownerid in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, 0WNER(X' E2E4C5 ' ) is the same as 
OWNER(SUE). 

READPWt pas sword) 

specifies a read password for the entry being altered. 

password 

i s a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb3, period C.3, 
single quote C'3, ampersand C&3, plus sign [+3, equal 
sign [=3, hyphen C-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3, enclose the password in 
single-quotation marks (for example, 
READPW( f *DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, READPW( » *CA" ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, READPW(X" E2E4C5 ' ) is 
the same as READPW(SUE). 
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Abbreviation: RDPW 

RECORDSIZEtaverage b maximum) 

specifies the new average and maximum lengths for the data 
records in the object. If the object whose entry is being 
altered is an alternate index path, the alternate index 
itself is altered; if the path points directly to its base 
cluster, then the base cluster is altered. If the object 
whose entry is being altered is an alternate index, the 
alternate key must be within the limit specified by 
maximum. For more information, see entryname. 

Restrictions- RECORDSIZE can be specified only if all of 
the following are true : 

• The object whose entry is being altered contains no 
data records. 

• The value for maximum RECORDSIZE in the catalog must be 
the default value. However, if a nondefau.lt value is 
altered and the new value matches the old, processing 
continues for any other parameters specified on the 
command. For default values, see the DEFINE command 
that defines the object. 

• The new maximum record length must be at least seven 
bytes less than control interval size, unless the 
record is a spanned record. 

• The new record length must be large enough to contain 
all prime and alternate keys previously defined. 

• For an alternate index, if NONUNIQUEKEY is specified, 
RECORDSIZE must account for the increased record size 
resulting from the multiple prime-key pointers in the 
alternate index data record. 

• The object whose entry is being altered is an alternate 
index, a cluster, a path, or a data component. 

Abbreviation: RECSZ 

REMOVEVOLUMES(volserCb volserl) 

has two uses : (1) REMOVEVOLUMES specifies volume(s) to be 
removed from the list of candidate volumes associated with 
the entry being altered. Volumes specified are removed 
after any new volumes are added to the candidate list. If a 
volume to be removed contains data that belongs to the 
entry being altered, the volume is not removed. For this 
use of REMOVEVOLUMES, the name of the data or index 
component must be specified in the entryname parameter. (2) 
REMOVEVOLUMES specifies volume(s) from which all VSAM data 
spaces are to be removed and VSAM ownership is to be taken 
away — without access to the user catalog that owns the 
volume(s). For this use of REMOVEVOLUMES, the name of the 
master catalog and its master password (if any) must be 
specified in the entryname parameter, and the FILE 
parameter is required. (You can have only one DD statement 
with this use of ALTER REMOVEVOLUMES — only volumes of the 
same device type can be processed.) See the section "VSAM 
Volume Cleanup" in the chapter "Data Security and 
Protection" and the section "VSAM Volume Recovery Function" 
in the chapter "Modifying Catalog Information" for 
information and cautions about this use of ALTER 
REMOVEVOLUMES. 

A volume serial number, volser, may contain one to six 
alphameric, national (2, #, and $), and special characters; 
the special characters include commas, blanks, semicolons, 
parentheses, slashes, asterisks, periods, quotation marks, 
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ALTER 

ampersands, plus signs* hyphens, and equal signs. A volume 
serial number must be enclosed in single quotation marks if 
it contains a special character. Single quotation marks 
within a volume serial number must be coded as two single 
quotation marks. 

Abbreviation: RVOL 

SCRATCH I NOSCRATCH 

specifies whether generation data sets are to be removed 
from the VTOC of the volume on which they reside when they 
are uncataloged (that i s> whether the data set's format-1 
DSCB i s removed — scratched — from the VTOC so that the data 
set can no longer be accessed) . 

Abbreviations: SCR and NSCR 

SHAREOPTIONSCcrossregionCb cross system] ) 

specifies how a data or index component of a cluster or 
alternate index can be shared among users (see Vi rtual 
Storage Access Method (VSAM) Programmer's Guide for a full 
description of data set sharing). This parameter can be 
specified only for the data or index components of clusters 
and alternate indexes. 

crossregion 

specifies the amount of sharing allowed among regions 
(within the same system). Independent job steps in sn 
operating system can access a VSAM data set 
concurrently. To share a data set, each user must 
specify DISP=SHR in the data set's DD statement. The 
values that can be specified are'* 

1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. #If a 
user desires read integrity, it is his 
responsibility to use the ENQ and DEQ macros 
appropriately to provide read integrity for the 
data his program obtains. 

3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data his program 
accesses. User programs that ignore the write 
integrity guidelines can cause VSAM program 
checks, lost or inaccessible records, 
uncorrectable data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

<t 

specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 
This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTION 3. 
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crosssystem 

specifies the amount of sharing allowed among systems. 
Job steps of two or more OS/VS operating systems can 
gain access to the same VSAM data set regardless of 
the disposition specified in each step's DD statement 
for the data set. To get exclusive control of the data 
set's volume, a task in one system issues the RESERVE 
macro. The level of cross-system sharing allowed by 
VSAM applies only in a multiple operating system 
environment. The values that can be specified ar&' 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data his program accesses. User programs that 
ignore wr i te-i ntegri ty guidelines can cause VSAM 
program checks, uncorrectable data set failures, 
and other unpredictable results. This option 
places heavy responsibility on each user sharing 
the data set. 

4 

specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. This option requires that you 
use the RESERVE and RELEASE macros to maintain 
data integrity while sharing the data set. 
Writing is limited to PUT-update and PUT-insert 
processing that does not change the high-used RBA 
if your program opens the data set with DISP=SHR. 
Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
environment specify DISP=SHR. Improper use of the 
RESERVE macro can cause problems similar to those 
described under SHAREOPTION 3. 

Abbreviation: SHR 

STAGE | BIND | CYLINDERFAULT 

specifies how a data or index component that is stored on a 
mass-storage volume is to be staged. These parameters can 
be specified only for the data or index component of a 
cluster or alternate index. 

STAGE 

indicates that the component is to be staged from mass 
storage to a direct access storage staging drive when 
the component is opened. 

BIND 

indicates that the component is not only to be staged, 

but also to be bound — that is, retained on the direct 

access storage staging drive until it is closed. 

CYLINDERFAULT 

indicates that the component is not to be staged when 
it is opened, but that data from it is to be staged as 
a processing program needs it. 

Abbreviation: CYLF 

TO(date)|FOR(days) 

specifies the retention period for the entry being altered. 
This cannot be specified for the data or index components 
of clusters, alternate indexes, or catalogs. 
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ALTER 

TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day, through which the entry is to be kept. 

FOR (days) 

specifies the number of days for which the entry is to 
be kept. The maximum number that can be specified is 
9999. If the number specified is through 1830, the 
cluster is retained for the number of days specified; 
if the number is between 1831 and 9999, the cluster is 
retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

UNIQUEKEY | NONUNIQUEKEY 

specifies whether the alternate-key value can be found in 
more than one of the base cluster's data records. UNIQUEKEY 
specifies that each alternate-key value is unique. If the 
same alternate-key value is found in more than one of the 
base cluster's data records, an error results. 

NONUNIQUEKEY allows you to have an alternate-index record 
that, for a given alternate-key value, might point to more 
than one data record in the cluster. 

i 
UNIQUEKEY can be specified only for an empty alternate 
index (that is, an alternate index that is defined but not 
yet bui It ) . 

NONUNIQUEKEY can be specified for an alternate index at any 
time. If the alternate index is empty, you should also 
consider specifying RECORDSIZE to ensure that each 
alternate index record is large enough to contain more than 
one data record pointer. 

Abbreviations: UNQK and NUNQK 

UPDATE | NOUPDATE 

specifies whether a base-cluster's alternate-index upgrade 
set is to be allocated when the path's name is allocated 
with a DD statement. 

NOUPDATE specifies that the path's cluster is to be 
allocated, but that the cluster's alternate-index upgrade 
set is not to be allocated. 

Abbreviations: UPD and NUPD 

UPDATEPW(password) 

specifies an update password for the entry being altered. 

password 

i s a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,], semicolon C;3, blank Cb3, period [.], 
single quote ['], ampersand t&3, plus sign [+], equal 
sign C=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk [*3, enclose the password in 
single-quotation marks (for example, 
UPDATEPWCXDORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, UPDATEPW( ' *CA"R0l* ' ) ) . 



Command Format 135 



You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, UPDATEPWCX* E2E4C5 ' ) is 
the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 

UPGRADE | NOUPGRADE 

specifies whether an alternate index is to be upgraded 
(that is, kept up to date) when its base cluster is 
modified. UPGRADE specifies that when the cluster's records 
are added to, updated, or erased, the cluster's alternate 
index is upgraded to reflect the changed data. 

If UPGRADE is specified when the cluster is open, the 
upgrade attribute does not apply to the alternate index 
until the cluster is closed and next opened (that is, a new 
set of VSAM control blocks describes the cluster and its 
attributes). 

UPGRADE can be specified only for an empty alternate index 
(that is, an alternate index that is defined but not 
built). However, the UPGRADE attribute is not effective for 
the alternate index until the alternate index is built (see 
the BLDINDEX command). 

NOUPGRADE can be specified for an alternate index at any 
time. 

Abbreviations: UPG and NUPG 

WRITECHECK I NOWRITECHECK 

specifies whether a data or index component is to be 
checked by a machine action called write-check when a 
record is written into it. If WRITECHECK is specified, a 
record is written and then read, without data transfer, to 
test for the data-check condition. 

Abbreviations: WCK and NWCK 
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ALTER 
ALTER EXAMPLES 
Alter a Cluster's Entry: Example 1 

In this example, an ALTER command is used to specify passwords 
for a nonindexed (entry-sequenced) cluster, D50 . EXAMPLE. ESDS1 . 
No password for the cluster is required, because the cluster was 
defined without passwords. 

//ALTER1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD X 
ALTER - 

D50. EXAMPLE. ESDS1 - 

MASTERPWCDEPT26M) - 

C0NTR0LPWCDEPT26C) - 

UPDATEPWCDEPT26U) - 

READPWCDEPT26R) - 

AUTHORIZATION (D26AUTH) 
/x 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The ALTER command adds passwords to the entry-sequenced 
cluster's cluster catalog entry. The passwords are not added to 
the cluster's data entry, however. If a user's program supplies 
the cluster's data entry entryname and opens the data component, 
the unauthorized user can access the cluster's data records even 
though the cluster itself is password protected. The ALTER 
command's parameters are- 

• D50 . EXAMPLE. ESDS1 , the name of the entry-sequenced cluster. 
It is assumed that an alias entry exists named D50 for the 
user catalog D27UCAT2. The data set name, D50 . EXAMPLE. ESDS1 , 
causes the ALTER request to be directed to D27UCAT2. 

• MASTERPW, CONTROLPW, UPDATEPW, READPW, and AUTHORIZATION, 
which specify passwords and the entryname of the 
user's-securi ty-veri fication routine. 

Alter the Entrynames of Generically Named Clusters: Example 2 

In this example, several clusters with similar names, 
GENERIC. x.BAKER (where "X" is any 1 to 8 character simple name), 
are renamed so that their entrynames are GENERIC. X . ABLE. The 
name "GENERIC. * . BAKER" is called a generic name. 

//ALTER2 JOB 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
ALTER - 

GENERIC. x.BAKER - 

NEWNAMEC GENERIC. x. ABLE) 
/x 

The job control language statements are* 

• JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Acess Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 
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The ALTER command changes each generic entryname, 
GENERIC. X.BAKER, to GENERIC. X .ABLE. Its parameters are: 

• GENERIC. x.BAKER, which identifies the objects to be 
modified, 

• NEWNAME, which specifies that each generic entryname 
GENERIC. *. BAKER is changed to GENERIC. x .ABLE. 

Alter the Attributes of a Generation Data Group: Example 3 

In this example, the attributes of a generation data group are 
modified. Because the attributes of the group are cataloged in 
the generation data group's base catalog entry, only this entry 
i s modi f i ed. 

//ALTER3 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD x 
ALTER - 

GDG01 - 

NOEMPTY - 

SCRATCH 
/x 

The job control language statements are' 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The ALTER command modifies some of the attributes of generation 
data group GDG01. Its parameters are- 

• GDG01, which identifies the object to be modified. 

• NOEMPTY, which specifies that only the oldest generation 
data set is to be uncataloged when the maximum number of 
cataloged generation data sets is exceeded. 

• SCRATCH, which specifies that the generation data set's DSCB 
is to be removed from the volume's VTOC when the data set is 
uncataloged. 

The attributes specified for the generation data group with the 
ALTER command override any attributes previously specified for 
the GDG. 
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BLDINDEX 



The format of the BLDINDEX command is: 



BLDINDEX 



(INFILE(dname[/password3 ) I 

INDAT AS ET( en try name [/password 3 )} 
{OUTFILE (dnameC /password] 
[b dnameL/password] . . . 3 ) | 
OUTDATASET ( entrynameC /password] 
Cb entrynameC/password] . . . 3 )} 
CCATALOGCcatnameC/password] )] 
CEXTERNALSORT I INTERNALS0RT 3 
[WORKFILESt dname b dname)] 



BLDINDEX can be abbreviated: 



BIX 



BLDINDEX PARAMETERS 



Required Parameters 



INFILEtdnameC/password] ) 

names the DD statement that identifies the base cluster or 
a path that points to the base cluster. If the base cluster 
or path is password protected> you can supply the read (or 
highei — level) password of the object named in the DD 
statement. Otherwise, the operator or TSO terminal user is 
prompted to supply the correct password. 

The base cluster must be defined in the same catalog as the 
alternate index, and must contain data records. 

The alternate index identified with OUTDATASET or OUTFILE 
must be related to the base cluster. 

Abbreviation: IFILE 

INDATASET(entrynameC/password3 ) 

names a base cluster or a path that points to the base 
cluster. If the base cluster or path is password protected, 
you supply the read (or highei — level) password of the named 
object. Otherwise, the operator or TSO terminal user is 
prompted to supply the correct password. When you specify 
INDATASET, the base-cluster's volume is dynamically 
allocated. Therefore, the base-cluster's volume must be 
mounted as permanently resident or reserved. 

The base cluster must be defined in the same catalog as the 
alternate index, and must contain at least one data record. 

The alternate index identified with OUTDATASET or OUTFILE 
must be related to the base cluster. 

Abbreviation: IDS 

OUTFI LEI dname E /password] [b dnameC/pas sword] . . . 3 ) 

names the DD statement that identifies the alternate index 
or a path that points to the alternate index. You can build 
more than one alternate index for the same base cluster by 
specifying more than one dname with the OUTFILE parameter. 
If the alternate index or path is password protected, you 
can supply the update- (or highei — level) password of the 
object named in the DD statement. Otherwise, the operator 
or TSO terminal user is prompted to supply the correct 
password. 

The alternate index must be defined in the same catalog as 
the base cluster, and must be empty (that is, its high-used 
RBA equals zero) or defined with the reusable attribute. 
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The alternate index must be related to the base cluster 
identified with INDATASET or INFILE. 

Abbreviation: OFILE 

OUTDATAS ET ( en trynameC/ password] 

Cb entrynameC/password] . . . ] ) 

names the alternate index or a path that points to the 
alternate index. You can build more than one alternate 
index for the same base cluster by specifying more than one 
entryname with the OUTDATASET parameter. If the alternate 
index or path is password protected* you supply the update 
(or highei — level) password of the named object. Otherwi se* 
the operator or TSO terminal user is prompted to supply the 
correct password. When you specify OUTDATASET* the 
alternate-index's volume is dynamically allocated. 
Therefore* the volume must be mounted as permanently 
resident or reserved. 

The alternate index must be defined in the same catalog as 
the base cluster* and must be empty (that is* its high-used 
RBA equals zero) or must have been defined with the REUSE 
attri bute. 

The alternate index must be related to the base cluster 
identified with INDATASET or INFILE. 

Abbreviation: ODS 



Optional Parameters 



CATALOGCcatnameC/passwordl ) 

names the catalog that the workfiles are to be defined in. 
The workfiles are defined and used by the BLDINDEX routine. 
When all alternate indexes are built and the workfiles are 
no longer needed by the BLDINDEX routine* they are deleted. 

password 

If the catalog is password protected* you can supply 
its update- (or highei — level) password. Otherwise* the 
operator is prompted to supply the correct password. 

See "Order of Catalog Use: BLDINDEX" for information about 
the order in which a catalog is selected when the CATALOG 
parameter is not specified. 

Abbreviation: CAT 

EXTERNALSORT I INTERNALSORT 

specifies whether the key-pointer pairs are to be sorted 
entirely within virtual storage. 

When you specify EXTERNALSORT* two external-sort workfiles 
are defined and built as VSAM entry-sequenced clusters. 

When you specify INTERNALSORT* or allow it to default, 
Access Method Services sorts the key-pointer pairs entirely 
within the usei — provided virtual storage if possible. If 
not enough virtual storage is provided for an internal 
sort* two external sort workfiles are built and the 
key-pointer pairs are sorted externally. If the minimum 
amount of virtual storage is not provided (see "How an 
Alternate Index is Built")* the BLDINDEX processing 
terminates with an error message. 

When you specify EXTERNALSORT* or if not enough virtual 
storage is provided for an internal sort* you must provide 
two DD statements that describe the external-sort workfiles 
to be defined by BLDINDEX. 

You can name the DD statements IDCUT1 and IDCUT2. When you 
choose other names for the workfile DD statements* you must 
identify the DD statements with the WORKFILES parameter. 
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BLDINDEX 



Abbreviations: ESORT and ISORT 



WORKFILES (dname b dname) 

names the DD statements that identify the workfiles you 
want BLDINDEX to define if an external sort of the 
key-pointer pairs is required. You can use DD statements to 
describe two workfiles that will be defined and opened 
before the BLDINDEX routine begins processing the 
base-cluster's data records. 

When you code the DD statements that describe the workfiles 
and identify them with the standard dnames IDCUT1 and 
IDCUT2> you do not need to specify the WORKFILES parameter. 

For information on how to code the DD statements that 
describe the workfiles* see "DD Statements that Describe 
the SORT Workfiles." 

Abbreviation: WFILE 
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BLDINDEX EXAMPLE 



This example builds an alternate index over a previously-defined 
base cluster, EXAMPLE. KSDS2. Data records have already been 
loaded into the base cluster, so that it is not empty. The 
alternate index, its path, and its base cluster are all defined 
in the same catalog, AMASTCAT. 

//BUILDAIX JOB . . . 

//STEP1 EXEC PGM=IDCAMS 

//BASEDD DD DSNAME=EXAMPLE. KSDS2 , DISP=0LD 

//AIXDD DD DSNAME=EXAMPLE.AIX,DISP=OLD 

//IDCUT1 DD DSNAME=SORT. WORK. ONE, DISP = 0LD, AMP=' AMORG' , 

// VOL=SER=VSER01,UNIT=2314 

//IDCUT2 DD DSNAME=SORT. WORK. TWO, DISP=OLD,AMP=' AMORG' , 

// VOL=SER=VSER01,UNIT=2314 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

BLDINDEX INFILECBASEDD) - 

OUTFILECAIXDD/AIXUPPW) - 
CATALOGCAMASTCAT/MCATUPPW) 
/* 

The job control language statements are: 

• BASEDD DD, which describes the base cluster. 

• AIXDD DD, which describes the alternate index. 

• IDCUT1 and IDCUT2 DD, which describe a volume containing 
VSAM data space to be made available to BLDINDEX for 
defining and using two sort work data sets in the event an 
external sort is performed. This data space will not be used 
by BLDINDEX if enough virtual storage is available to 
perform an internal sort. 

The BLDINDEX command builds an alternate index. The assumption 
is made that enough virtual storage will be available to perform 
an internal sort. However, note that DD statements with the 
default dnames of IDCUT1 and IDCUT2 have been provided for two 
external sort work data sets in the event that the assumption is 
incorrect and an external sort must be performed. The BLDINDEX 
command's parameters are : 

• INFILE, which names the base cluster. The dname of the DD 
statement for this object must be identical to this name. 
Note that a password is not required since the base cluster 
is not protected. 

• OUTFILE, which names the alternate index. The dname of the 
DD statement for this object must be identical to this name. 
The update password of the alternate index is also required. 

• CATALOG, which identifies the master catalog. If it is 
necessary for BLDINDEX to use external sort work data sets, 
they will be defined in and deleted from the master catalog. 
The update password will permit these actions. 
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CHKLIST 



CHKLIST 



The format of the CHKLIST command is ; 



CHKLIST 



INFILE(dname) 
CCHECKIDtcheckid... )] 
[OUTFILE(dname)3 



CHKLIST can be abbreviated: CKLST. 



CHKLIST PARAMETERS 



Required Parameter 



INFILE(dname) 

specifies the name of the DD statement that identifies the 
checkpoint data set that contains the checkpoint entries to 
be processed. 



Abbreviation: IFILE 



Optional Parameters 



CHECKIDC checkid... ) 

specifies one or more checkpoint identifiers of entries in 
the checkpoint data set for which to list tape data sets 
that were open at the time of the checkpoint. Each checkid 
must be one to sixteen characters in length. It must be 
enclosed in single quotation marks if it contains commas, 
semicolons, blanks, parentheses, slashes, or asterisks. The 
checkid must be the same as was specified in the CHKPT 
macro. A maximum of 255 checkids can be specified. Multiple 
checkids may be specified in any sequence. 

If CHECKID is omitted, identification of tape data sets 
that were open at the time of a checkpoint are listed for 
all entries in the checkpoint data set. CHECKID must be 
omitted when a member of a partitioned checkpoint data set 
has been specified after dsname in the DD statement 
identified by INFILE. 

If the checkpoint data set contains duplicates of a 
checkid, you can cause all of the checkpoint entries with 
that checkid to be listed either by specifying the checkid 
at least twice or by specifying, along with the checkid, a 
checkid for which there is no entry in the checkpoint data 
set. If you do neither, only the first checkpoint entry 
found with the checkid is listed. 

Abbreviation: CHKID 

OUTFILE(dname) 

specifies the ddname of the DD statement that identifies a 
data set other than the SYSPRINT data set to be used as an 
output data set. An output data set must meet the 
requirements shown under "Output Data Sets" in the 
"Introduction." If OUTFILE is not specified, the tape data 
set information is listed in the SYSPRINT data set. 

Abbreviation: OFILE 
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CHKLIST EXAMPLES 

Selecting Specific Checkpoint Entries: Example 1 

In this example* the tape data sets that were open at checkpoint 
time are identified and listed on SYSPRINT for checkpoint 
entries C0000001 and C0000002. 

//CHKLIST1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//CHKPT DD DSN=CHKPT.DATASET*DISP=OLD 
//SYSIN DD x 
CHKLIST - 

INFILE(CHKPT) - 
CHECKIDCC0000001 C0000002) 
/x 

The job control statements are* 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are sent. 

• CHKPT DD* which identifies the checkpoint data set that 
contains the entries for which the tape data set information 
is to be li sted. 

The CHKLIST command prints the tape data set information as 
specified by the command's parameters' 

• INFILE* which points to the CHKPT DD statement. The CHKPT DD 
statement identifies the checkpoint data set. 

• CHECKID* which specifies that the checkpoint entries with 
checkids C0000001 and C0000002 are the only ones on the 
checkpoint data set for which the tape data set information 
is to be li sted. 

The output shown in "Appendix E. Sample Output From CHKLIST" was 
obtained with this JCL. 

Partitioned Checkpoint Data Set: Example 2 

In this example* the checkpoint data set is a partitioned data 
set* and member C0000001 is selected for processing bvr CHKLIST. 

//CHKLIST2 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//CHKPTDD DD DSN=EXAMPLE.CHKPTDS2(C0000001) * 
// DISP=SHR 
//SYSIN DD * 
CHKLIST - 

INFILE(CHKPTDD) 
/* 

The job control language statements are: 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

• CHKPTDD DD* which identifies the partitioned checkpoint data 
set and the specific member for which the tape data set 
information is to be listed. 
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CHKLIST 

The CHKLIST command prints the tape data set information as 
specified by its parameter, INFILE, which points to the CHKPTDD 
DD statement. The CHKPTDD DD statement identifies the member of 
the partitioned checkpoint data set. 

Note: The CHECKID parameter is omitted so that the checkpoint 
entry C0000001 will automatically be processed by CHKLIST. 
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The format of the CNVTCAT command is 



CNVTCAT 



{INFILE(dname)|INDATASET(entryname)} 
[CATALOG(catnameL/password3 )3 
ECVOLEQUATES((catname btvolser 

Cb volser...]) )Cb(catname. ..)... 3 )3 
[ LIST IN0LIST3 
CMASTERCATAL0G(catname[/password3 )3 



CNVTCAT can be abbreviated: CNVTC 



CNVTCAT PARAMETERS 



Required Parameters 



INFILE(dname) 

specifies the name 
catalog that is to 



of 
be 



a DD statement 
converted. 



that identifies the OS 



Abbreviation: IFILE 



INDATASET C en t ryname ) 

specifies the control-volume-pointer (CVPE) name (not the 
data set name) of the OS catalog that is to be converted. 
If INDATASET is specified, the OS catalog is dynamically 
allocated. The OS system catalog entryname, SYSCTLG, cannot 
be specified. If entries in the system catalog are being 
converted, INFILE must be used to specify a DD statement 
that identifies the OS system catalog. 

Abbreviation: ids 



optional Parameters 



CATAL0G(catnamet/password3 ) 

specifies the name of a catalog that is to receive the 
converted entries. If CATALOG is not specified, see "Order 
of Catalog Use: CNVTCAT* ' for information about the order 
in which a catalog is selected. 



password 

speci f i es, 
update- or 



for a password-protected catalog, 
highei — level password. 



the 



Abbreviation: CAT 



)3 



CVOLEQUATESC (catname bCvolserCb volser. .. 3 ) )Cb(catname. 
identifies the user catalog that converted 
control-volume-pointer entries (CVPEs) point to. CVPEs 
point to control volumes (CVOLs) which contain OS catalog 
entries. The OS catalog entries in a CVOL might have been 
(or might soon be) converted to VSAM catalog entries and 
put into a user catalog. When a CVPE is converted to an 
alias entry, the alias entry points to the user catalog 
that contains (or is to contain) the control volume's 
converted OS catalog entries. 



When you specify CVOLEQUATES, 
MASTERCATALOG. 



you must also specify 



catname 

specifies the name of an existing VSAM catalog. The 
catalog named contains or is to contain converted OS 
catalog entries that were cataloged in the CVOL 
pointed to by the CVPE being converted. 
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volser 

specifies the volume serial number(s) of one or more 
CVOLS for which entries have been or are to be 
converted. 

Abbreviation: CVEQU 

LIST lNQLIST 

specifies whether entries are to be listed after they are 
converted. 

Abbreviation: NLST 

MAST ERCATALOG( cat name [/password] ) 

specifies the name of the master catalog into which any 
aliases for user catalogs are to be placed. MASTERCATALOG 
is required when CVOLEQUATES is specified. 

password 

specifies the master catalog's update- or highei — level 
password. 

Abbreviation: MCAT 
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//CNVTCAT1 


JOB 


//STEP1 


EXEC 


//SYSPRINT 


DD 


//0SCAT1 


DD 



CNVTCAT EXAMPLES 

The two CNVTCAT examples are related and show how the entries of 
two catalogs in an OS system can be converted to entries in a 
VSAM catalog. The catalog on volume VSER09 contains 
control-volume-pointer entries (CVPEs) that point to the catalog 
on volume VSER08. Therefore* the two catalogs ar& chained 
together with VSER08's catalog at the end of the chain. When two 
or more OS catalogs are chained together, the catalog at the end 
of the chain should be converted first. 

Convert an OS Catalog's Entries to Entries in a VSAM Catalog: Example 1 

In this example, the entries in the catalog on volume VSER08 are 
converted to VSAM catalog entries and written into the USER11 
catalog. 

CAT1 JOB 

PGM=IDCAMS 
SYS0UT=A 

VOL=SER=VSER08,DISP=OLD,DSN=SYSCTLG, 
// UNIT = 231<+ 
//SYSIN DD x 
CNVTCAT - 

INFILEC0SCAT1) - 
CATAL0GCUSER11/MR) 
/x 

The job control language statements are : 

• 0SCAT1 DD, which describes and allocates the OS catalog that 
is to be converted. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The CNVTCAT command converts the entries in the OS catalog on 
volume VSER08 to entries in a user catalog, USER11. The 
command's parameters are : 

• INFILE, which points to the 0SCAT1 DD statement. The 0SCAT1 
DD statement describes and allocates the OS catalog that is 
to be converted. 

• CATALOG, which specifies the name of an existing VSAM 
catalog, the user catalog USER11. USER11 is to receive the 
converted entries. The user catalog's update- (or 
highei — level) password, MR, is required. 
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//CNVTCAT2 


JOB 


//STEP1 


EXEC 


//SYSPRINT 


DD 


//0SCAT2 


DD 



CNVTCAT 

Convert an OS Catalog's Entries to Entries in a *VSAM Catalog: Example 2 

In this example, the entries in the OS catalog on volume VSER09 
are converted to VSAM catalog entries and written into the 
USER12 catalog. Some of the entries in the OS catalog are 
control volume pointer entries, and point to the OS catalog on 
volume VSER08 (which was converted in the previous example). 

PGM=IDCAMS 
SYS0UT=A 

VOL=SER=VSER0 9,DISP=OLD,DSN=SYSCTLG, 
// UNIT=2314 
//SYSIN DD * 
CNVTCAT - 

INFILEC0SCAT2) - 
CATAL0GCUSER12/MR) - 
CVOLEQUATESC - 

(USER11 (VSER08)) ) - 
NOLIST - 

MASTERCATALOG(AMASTCAT) 
/* 

The job control language statements are' 

• 0SCAT2 DD, which describes and allocates the OS catalog that 
is to be converted. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The CNVTCAT command converts the entries in the OS catalog on 
volume VSER09 to entries in a user catalog, USER12. Because 
CVOLEQUATES is specified, an alias entry is built and put in the 
master catalog to relate the name VSER08 to the user catalog 
USER11. The command's parameters are'- 

• INFILE, which points to the 0SCAT2 DD statement. The 0SCAT2 
DD statement describes and allocates the OS catalog to be 
converted. 

• CATALOG, which specifies the name of an existing VSAM 
catalog, the user catalog USER12. USER12 is to receive the 
converted entries. The user catalog's update- (or 
highei — level) password, MR, is required. 

• CVOLEQUATES, which specifies that control-volume-pointer 
entries (CVPEs) are to be converted to alias entries. Each 
CVPE in VSER09's catalog points to an entry in VSEROS's 
catalog. Each new alias entry points to the USER11 user 
catalog connector entry in the master catalog. The alias 
entries are written into the master catalog. 

• NOLIST, which specifies that the entries are not to be 
listed after they are converted. 

• MASTERCATALOG, which identifies the master catalog. This 
parameter must be specified because CVOLEQUATES is also 
specified. If the master catalog is password protected, the 
catalog's update- (or highei — level) password must be 
speci f i ed. 
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DEFINE ALIAS 



The format of the DEFINE command when it is used to define an 
alias i s J 



DEFINE 


ALIAS 




(NAME(aliasname) 




RELATE(entryname) ) 




CCATAL0G(catname[/password3 )3 



DEFINE may be abbreviated: DEF. 
DEFINE ALIAS PARAMETERS 

Required Parameters 

ALIAS 

specifies that an alias for a user catalog or nonVSAM data 
set is to be defined. 

NAMECal i asname) 

specifies the alias — the alternate entryname for a user 
catalog or nonVSAM data set. 

aliasname can contain 1 to 44 alphameric characters (A 
through Z, and through 9), national characters (3), #, and 
$), and special characters (the hyphen (-), and the 12-0 
overpunch (X'CO')). 

When the name contains more than eight characters, you 
divide the name into segments of 1 to 8 characters each and 
separate the segments with (.) periods. 

The name's first character (and each segment's first 
character) is either an alphabetic character or a national 
character. 

RELATE ( entryname ) 

specifies the name of the entry (that is, the usei — catalog 
entryname or the nonVSAM data set name) for which the alias 
is being defined. 

An alias entry must reside in the same catalog as the entry 
to which it is related. When an alias is defined, catalogs 
are searched for the related entry. When the related entry 
is found, the alias entry is added to the catalog. An alias 
must be unique within a catalog. An alias can be defined 
only for a nonVSAM data set or for a usei — catalog connector 
in the master catalog. 

Abbreviation: REL 



Optional Parameter 



CATALOG(catnameC/password] ) 

identifies the catalog in which the alias is to be defined 
If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. See "Order of Catalog 
Search 2 DEFINE" for information about the order in which a 
catalog is selected when the catalog's name is not 
specified. 

catname 

specifies the name of the catalog. When the alias is 
for a user catalog connector, catname is the name of 
the master catalog. 
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password 

specifies a password. If the catalog is password 
protected, you must supply the catalog's update- or 
hi ghei — level password. If no password is specified and 
the catalog is password protected, VSAM asks the 
operator or TSO terminal user for the correct 
password. 

Abbreviation: CAT 
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DEFINE ALIAS EXAMPLES 

Define an Alias for a NonVSAM Data Set: Example 1 

In this example; an alias is defined for a nonVSAM data set. 

//DEFALS JOB 

//STEP1 EXEC PGM=IDCAMS 
//STEPCAT DD DSNAME=D27UCAT1 , DISP=0LD 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DEFINE ALIAS - 

(NAME(EXAMPLE.NONVSAMl) - 
RELATE(EXAMPLE. NONVSAM) ) 
/* 

The job control language statements are: 

• STEPCAT DD, which makes a catalog available for this job 
step: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE ALIAS command defines an alias, EXAMPLE. N0NVSAM1 , for 
the nonVSAM data set EXAMPLE. NONVSAM. Its parameters are'* 

• NAME, which specifies the alias (alternate entryname), 
EXAMPLE. N0NVSAM1. 

• RELATE, which specifies the name that the alias is an 
alternate entryname for, EXAMPLE. NONVSAM. 

Define an Alias for a User Catalog: Example 2 

In this example, an alias is defined for a user catalog. The 
alias is defined in the master catalog. 

//DEFUCALS JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DEFINE ALIAS - 

(NAMECD40) - 

RELATECD27UCAT1)) - 

CATALOG (AMASTCAT/MCATUPPW) 
/* 

The job control statements are'' 

• SYSPRINT, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE ALIAS command defines an alias, D40, for the VSAM 
user catalog, D27UCAT1. Any data set defined in D27UCAT1 having 
'D40' as its first qualifier will be located by VSAM in D27UCAT1 
when it is referenced in an Access Method Services command or 
user program without requi pi ng a JOBCAT or STEPCAT DD statement 
for D27UCAT1. D27UCAT1 can also be referenced using the alias 
D40. The parameters are= 

• NAME, which specifies the alias, D40. 

• RELATE, which specifies the name of the user catalog for 
which D40 is an alternate entryname (alias). 

• CATALOG, which supplies the update password of the master 
catalog. 
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DEFINE ALTERNATEINDEX 



When you define an alternate index, you can specify attributes 
for the alternate index as a whole and for the alternate-index's 
components. The format of the DEFINE ALTERNATEINDEX command is: 

DEFINE ALTERNATEINDEX (parameters) - 

CDATA(parameters) ] - 

[INDEX(parameters)] - 

CCATALOG(subparameters)] 
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DEFINE 



ALTERNATEINDEX 
(NAME (en try name) 
RELATE(entryname[/password] ) 
{CYLINDERS(primaryCb secondary] ) | 

RECORDS(primary[b secondary])} 

TRACKS(primary[b secondary])} 
VOLUMES(volserCb volser...]) 
[ATTEHPTS(number|2)] 

CAUTHORIZATION(entrypointCb string])] 
[BUFFERSPACE(size)] 
CCODE(code)] 

[CONTROLINTERVALSIZE(size)] 
CCONTROLPW( password)] 
[DESTAGEMAITl NQDESTAGEHAIT ] 
[ERASElNOERASE] 
CEXCEPTIONEXIT(entrypoint)] 
CFILE(dname)] 

CFREESPACE(CI-percentCb CA-percent] I 0)] 
CltlBEDlNOIMJED] 
CKEYRANGES((lo'wkey b highkey) 

[(lowkey b highkey)...])] 
[KEYSXlength b offset|64 0)] 
CMASTERPW(password)] 
[MODEL ( en try name C /pas sword] 

[b catnameC/password] ] )] 
[ORDERED I UNORDERED ] 
[OWNER(ownerid)] 
EREADPW( password)] 
[REC0RDSI2E(average b maximum! 

4086 32600 )] 
[REPLICATE 1 NQREPLICATE ] 
[REUSE I NOREUSE ] 
[SHAREOPTIONS(crossregi on 

[b crosssystem] | 1 3)1 
[SPEED 1 RECOVERY] 

[ sj_agi I bindTcylinderfault ] 

[TO(date)|FOR(days)] 
[UNIQUE I SUBALLOCATION ] 
[UNIQUEKEY 1 NOHUNIQUEKEY ] 
[UPDATEPW( password)] 
[ UPGRADE I NQUPGRADE] 
[NRITECHECK I NOKRITECHECK] ) 



(Continued on next page.) 
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[DATA 

(CATTEMPTS(number)] 

CAUTHORIZATIONCentrypointCb string])] 

[BUFFERSPACE(size)] 

[CODE(code)] 

[CONTROLINTERVALSIZE(size)] 

[CONTROLPU( password)] 

CCYLINDERStprimaryCb secondary] ) | 

RECORDS(primary[b secondary])! 

TRACKSCprimaryCb secondary])] 
CDESTAGEWAITlNODESTAGEWAIT] 
[ERASEINOERASE] 
CEXCEPTIONEXIT(entrypoint)] 
CFILE(dname)] 

[FREESPACECCI-percentEb CA-percent] )] 
[KEYRANGESUlowkey b highkey) 

[(lowkey b highkey)...])] 
CKEYSdength b offset)] 
CMASTERPW(password)] 
[ MODEL t en try name C /password] 

Cb catnameE/password] ] )] 
[NAME (en try name) ] 
[ORDERED | UNORDERED] 
[OWNERtownerid)] 
[READPWCpassword)] 
[RECORDSIZE(average b maximum)] 
[REUSElNOREUSE] 

[SHAREOPTIOHS(crossregion[b crosssystem] )] 
[SPEEDlRECOVERY] 
[STAGE | BIND | CYLINDERFAULT] 
[UNIQUE I SUBALLOCATION] 
[UNIQUEKEYlNONUNIQUEKEY] 
[UPDATEPU(password)] 
[VOLUMESCvolsertb volser...])] 
[WRITECHECKINOWRITECHECK] )] 

[INDEX 

UATTEMPTS(number)] 

[AUTHORIZATION(entry P oint[b string])] 
[CODE(code)] 

[CONTROLINTERVALSIZE(size)] 
ECONTROLPWC password)] 
[CYLINDERS(primary[b secondary] ) | 

RECORDS(primary[b secondary])! 

TRACKSCprimary[b secondary])] 
[DESTAGEWAITINODESTAGEWAIT] 
[EXCEPTIONEXITCentrypoint)] 
[FILE(dname)] 
[IMBED | NOI MB ED] 
[MASTERPW(password)] 
[ MODEL ( en try name [ /password] 

[b catname[/password] ] ) ] 
[NAME (en try name)] 
[ORDERED | UNORDERED] 
[OWNER(ownerid)] 
[READPW( password)] 
[REPLICATE i NOREPLICATE] 
[REUSElNOREUSE] 

[SHAREOPTIONS(crossregi on[b crosssystem] )] 
[STAGE I BIND I CYLINDERFAULT] 
[UNIQUE I SUBALLOCATION] 
[UPDATEPW( password)] 
[VOLUMES(volser[b volser...])] 
[ WRITECHECK | NOWRITECHECJC] ) ] 

[CATALOG(catname[/password] )] 
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DEFINE ALTERNATEINDEX Parameters: summary 



The parameters of the DEFINE ALTERNATEINDEX command can be 
grouped as required and optional parameters. 

The required parameters are' 

• Entry type, which specifies that an alternate index and its 
catalog entry are to be created (ALTERNATEINDEX). 

• Name, which names the alternate index (NAME). 

• Base cluster, which identifies the base cluster related to 
the alternate index (RELATE). 

• Allocation, which specifies the amount of space to be 
allocated to the alternate index and identifies the 
volume(s) that is to contain the alternate index (VOLUMES 
and one of CYLINDERS, RECORDS, or TRACKS). You need not 
explicitly specify the allocation parameters if you use the 
MODEL parameter . 

The optional parameters are* 

• Model, which identifies an existing alternate index entry 
that is to be used as a model for the alternate index being 
defined (MODEL). 

• Allocation, which specifies 

the name of the DD statement that describes the 
alternate-index's volume(s) (FILE). 

the length and offset of the alternate-key field in the 
base cluster (KEYS). 

whether the alternate-index records are to be divided by 
alternate-key value among volumes (KEYRANGES). 

whether the alternate-key value can identify more than 
one data record in the base cluster (UNIQUEKEY or 
NONUNIQUEKEY). 

the size of control intervals, records, and the user 
program's buffer area (CONTROLINTERVALSIZE, RECORDSIZE, 
and BUFFERSPACE). 

how an alternate index or component that is stored on a 
mass storage device is to be staged (STAGE, BIND, or 
CYLINDERFAULT). 

the amount of free space to be left in control intervals 
and control areas when the alternate-index records are 
loaded (FREESPACE). 

whether the alternate index is to share its data space 
with other VSAM objects (SUBALLOCATION or UNIQUE). 

whether the volumes are to be allocated in the order 
given with the VOLUMES parameter (ORDERED or UNORDERED). 

whether the alternate index is to be temporary and 
reusable (REUSE or NOREUSE). 

• Data integrity, which specifies 

the name of a usei — written I/O error routine 
(EXCEPTIONEXIT). 

whether alternate-index records are to be overwritten 
with zeros when the alternate index is deleted (ERASE or 
NOERASE). 
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whether the alternate index can be shared among 
subtasks, jobs, and systems (SHAREOPTIONS) . 

whether the alternate-index records are to be checked 
when the direct access device writes them into secondary 
storage (WRITECHECK or NOWRITECHECK) . 

whether an alternate index or component, stored on a 
mass storage volume, is to be destaged synchronously or 
asynchronously with respect to the user's program that 
closes it (DESTAGEWAIT or NODESTAGEWAIT) . 

whether space is to be Preformatted when the alternate 
index is initially loaded (RECOVERY or SPEED). 

whether VSAM is to upgrade the alternate index each time 
its base cluster is modified (UPGRADE or NOUPGRADE) . 

• Protection, which 

specifies passwords for the alternate index (MASTERPW, 
CONTROLPW, UPDATEPW, and READPW) . 

identifies the alternate index to a console operator 
without revealing its entryname (ATTEMPTS and CODE). 

identifies a usei — wri tten-securi ty-veri f i cat i on rout i ne 
for additional authorization verification 
(AUTHORIZATION). 

identifies the alternate index's owner (OWNER). 

specifies a retention period for the alternate index 
(FOR or TO). 

• Parameters that apply to the index of an alternate index, 
which specify 

whether index records are to be repeated around the 
track of the index's direct access device (REPLICATE or 
NOREPLICATE). 

whether the index's sequence-set records are to be 
written adjacent to their data control areas (IMBED or 
NOIMBED). 

• Components, which specifies attributes for the 
alternate-index's data and index components that might 
differ from the attributes specified for the alternate index 
as a whole or the attributes established for the alternate 
index being used as a model (DATA and INDEX). 

• Catalog, which identifies the catalog in which the alternate 
index is to be defined (CATALOG). 

DEFINE can be abbreviated DEF. 
DEFINE ALTERNATEINDEX PARAMETERS 

Required Parameters 

ALTERNATEINDEX 

specifies that an alternate index is to be defined and have 
space allocated. 

The ALTERNATEINDEX keyword is followed by the parameters 
specified for the alternate index as a whole. These 
parameters are enclosed in parentheses and, optionally, are 
followed by the DATA and INDEX parameters and their 
subparameters. 
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Abbreviation: AIX 

NAME (en try name) 

specifies the alternate-index's entryname or the name of 
each of its components. The entryname specified for the 
alternate index as a whole is not propagated to the 
alternate-index's components. You can define a separate 
entryname for the alternate index, its data component, and 
its index component. If no name is specified for the data 
and index component, a name is generated. Because the 
alternate index, data component, and index component are 
individually named, each can be addressed. 

NAME is a required parameter of ALTERNATEINDEX. When NAME 
is not specified as a parameter of DATA or INDEX, VSAM 
generates an entryname for the alternate-index's 
components. 

entryname 

can contain 1 to 44 alphameric characters (A through 
Z, and through 9), national characters O, #, and 
$), and special characters (the hyphen (-), and the 
12-0 overpunch CX'CO')). 

When the name contains more than eight characters, you 
divide the name into segments of 1 to 8 characters 
each and separate the segments with (.) periods. The 
name's first character (and each segment's first 
character) is either an alphabetical character or a 
national character. If you specify the name in the 
format entryname(modi f i er) , only that portion of the 
name preceding the left parenthesis will be used. The 
modifier enclosed in parentheses will be ignored. 

RELATE(entryname[/password] ) 

names the alternate-index's base cluster. The base cluster 
is an entry-sequenced cluster or a key-sequenced cluster 
that the alternate index is to be organized over. 

You can relate an alternate index only to a key-sequenced 
cluster or to an entry-sequenced cluster. You cannot relate 
an alternate index to a reusable cluster or to a 
relative-record cluster. 

entryname 

names the base cluster. 

password 

specifies the base cluster's master password. 

You must specify the base cluster's master password 
when the base cluster is password protected. If you do 
not specify the base cluster's master password, you 
can specify the catalog's master password (that is, 
the master password of the catalog that contains the 
base cluster's entry — see the CATALOG parameter). If 
no password is specified with either the RELATE or the 
CATALOG parameter, VSAM asks the operator for the base 
cluster's master password. 

Abbreviation: REL 

CYLINDER5(primary[b secondary])! 

RECORDSfprimaryLb secondary)! 

TRACKSCpr imaryCb secondary]) 

specifies the amount of space to be allocated to the 
alternate index from the volume's available space, when 
UNIQUE is specified, or from the available space of one of 
the volume's VSAM data spaces. If you specify RECORDS, the 
amount of space allocated is the minimum number of tracks 
that are required to contain the specified number of 
records. However, if you specify TRACKS or RECORDS and if 
the minimum number of tracks should exceed a cylinder, 
space is allocated in terms of cylinders. 
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When UNIQUE is specified and the data component is to be 
contained on more than one volume, each volume can contain 
a maximum of 16 extents. 

When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
space is allocated only on the first volume when the 
component is defined. When the component increases in size 
so as to extend on to additional volumes, the first 
allocation on each overflow volume is the primary amount. 

When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
space is immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 

secondary amounts can be allocated on all volumes available 
to contain parts of the alternate index regardless of the 
key ranges when the alternate index is extended. 

The primary and each secondary allocation must be able to 
be satisfied within 5 extents; otherwise, your DEFINE or 
data set extension will fail. 

If you do not specify the MODEL parameter, you must specify 
one, and only one, of the following parameters? CYLINDERS, 
RECORDS, or TRACKS. You can specify the amount of space as 
a parameter of ALTERNATEINDEX, as a parameter of DATA, or 
as a parameter of both DATA and INDEX. If the space is 
specified as a parameter of : 

• ALTERNATEINDEX, the amount specified is divided between 
the data and index components. The division algorithm 
is a function of control interval size, record size, 
device type, and other data set attributes. If the 
division results in an allocation for the data 
component which is not an integral multiple of the 
required control-area size, the data component's 
allocation is rounded up to the next higher 
control-area multiple. This rounding may result in a 
larger total allocation for your alternate index than 
that which you specified. 

• DATA, the entire amount specified is allocated to the 
data component. An additional amount of space, 
depending on control interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 

When you specify UNIQUE, and the amount of space you 
specify for the data component of the alternate index is 
not an even multiple of cylinder size, VSAM rounds the 
allocation upward to a multiple of a cylinder. 

To determine the exact amount of space allocated to each 
component, list the alternate-index's catalog entry, using 
the LISTCAT command. 

When you specify UNIQUE and the alternate-index's data 
space is the first data space on a volume that belongs to a 
recoverable catalog, one additional cylinder is allocated 
for the catalog recovery area. 

primary 

specifies the initial amount of space that is to be 
allocated to the alternate index. 
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secondary 

specifies the amount of space that is to be allocated 
each time the alternate index extends, as a secondary 
extent. When secondary is specified, space for the 
alternate-index's data and index components can be 
expanded to include a maximum of 123 extents. 

If the data space that contains (all or part of) the 
cluster cannot be extended because the cluster's 
secondary allocation amount is greater than the 
data-space's secondary allocation amount, VSAM builds 
a new data space. The new data space's primary and 
secondary allocation amounts are equal to the 
cluster's secondary allocation amount. 

primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

Abbreviations: CYL, REC, and TRK 

VOLUMESCvolserCb volser...]) 

specifies the volume(s) on which an alternate-index's 
components are to have space. 

If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of ALTERNATEINDEX, or as a 
subparameter of both DATA and INDEX. If the data and index 
components are to reside on different device types, you 
must specify VOLUMES as a parameter of both DATA and INDEX. 

If more than one volume is listed with a single VOLUMES 
parameter, the volumes must be of the same device type. The 
volume serial number may be repeated in the list only if 
the KEYRANGE parameter is specified. You may wish to do 
this in order to have more than one keyrange on the same 
volume. Even in this case, repetition is only valid if all 
duplicate occurrences arQ used for the primary allocation 
of some keyrange. 

In a system with the Mass Storage System, an alternate 
index or component can be defined on a mass storage volume. 

volser 

i s a 1 to 6 alphameric or special character volume 
serial number. 

If the volser contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the volser contains a special character (that is, 
a comma [,3, semicolon [;], blank Cb3, period C.3, 
single quote C*3, ampersand [&], plus sign [ + 3, equal 
sign [=3, hyphen [-3 , parenthesi s C( or )3, slash C/3, 
or asterisk'!!*]), enclose the volser in 
single-quotation marks (for example, 
V0LUMES('*D0RIS')). 

When the volser contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, V0LUMES( ' *CA" ROL ' ) ) . 

You can code volser in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, V0LUMES(X' E2E4C5 ' ) is 
the same as VOLUMES(SUE) . 

The VOLUMES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure 
that the volume(s) you specify for the alternate index can 
satisfy the alternate index's other attributes 1 



160 0S/VS2 Access Method Services 



DEFINE ALTERNATEINDEX 



SUBALLOCATION: If UNIQUE is not specified, the volume 
must already contain VSAM data space. 

KEYRANGES: If KEYRANGES and UNIQUE are specified, a 
VSAM data space is built and allocated on a separate 
volume for each key range. 

ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-for-one correspondence 
between the key ranges in the key range list and the 
volumes in the volser list. 

CYLINDERS, RECORDS, TRACKS: The volume(s) contains 
enough available space to satisfy the component's 
primary space requirement. 

FILE: When UNIQUE is specified for the alternate index, 
the volume information supplied with the DD statement 
pointed to by FILE is consistent with the information 
specified for the alternate index and its components. 

CATALOG: If the volume already has a data space on it, 
subsequent data spaces can be defined for the alternate 
index and must be cataloged in the catalog that owns 
the volume. 

Abbreviation: VOL 



Optional Parameters 



ATTEMPTS(number|2) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

This parameter can be coded, but only has effect when the 
alternate-index's master password is not null. A prompting 
message is issued only when the user has not already 
supplied the appropriate password. 

number 

is an integer from to 7 and can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

When ATTEMPTS(O) is coded, the operator is not 
prompted and is not allowed to enter a password from 
the console. 

Note to TSO users: At a TSO terminal, the logon password is 
checked first before the user is prompted to supply a 
password for the alternate index. Checking the logon 
password counts as one attempt to obtain a password. If 
ATTEMPTS is not specified, the user has one attempt to 
supply the alternate-index's password because the default 
i s 2 . . " 

Abbreviation: ATT 

AUTHORIZATIONCentrypointCb string]) 

specifies that a usei — security-verification routine (USVR) 
is available for additional security verification. When a 
protected alternate index is opened and the user supplies a 
correct password other than the alternate-index's master 
password, the USVR receives control. For details on coding 
a USVR, see the OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide . 

If a USVR is loaded from an unauthorized library during 
Access Method Services processing, an abnormal termination 
will occur. See the sect i on "Authori zed Program Faci li ty" 
in the chapter "Introduction." 
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This parameter can always be coded/ but only has effect 
when the master password is not null. 

entrypoi nt 

specifies the name of the USVR. entrypoi nt can contain 
1 to 8 alphameric characters (A through Z and 
through 9) or national characters (2, #, $), and 
special characters (the hyphen (-) and the 12-0 
overpunch (X'CO')). The name's first character is 
either an alphabetic character or a national 
character. 

string 

specifies information to be passed to the USVR when it 
receives control to verify authorization, string can 
contain 'l to 255 EBCDIC characters. 

When the string contains a special character (that is, 
a comma C,3, semicolon C;3, blank Cb3, period [.3, 
single quote ['3, ampersand [&3, plus sign t + 3, equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash [/3 , 
or asterisk [*3), enclose the string in 
single-quotation marks (for example, AUTHORIZATION 
entrypoint, '*D0RIS*')). 

When the string contains a special character and also 
contains a single-quotation mark* code the imbedded 
quotation mark as two single-quotation marks (for 
example, AUTHORIZATION entrypoint, ' *CA"R0L*' ) ) . 

You can code string in hexadecimal form,- where two 
hexadecimal characters represent one EBCDIC character. 
For example, AUTHORIZATION entrypoi nt, X' E2E4C5 ' ) is 
the same as AUTHORIZATION entrypoint, SUE). The 
string can contain up to 255 hexadecimal characters 
when expressed in this form, resulting in up to 128 
bytes of information. 

Abbreviation: AUTH 

BUFFERSPACE! size) 

specifies the minimum space that your program's address 
space is to provide for buffers. The buffer space size you 
specify helps VSAM determine the data component's and index 
component's control interval size. 

If the specified size is less than VSAM requires for the 
buffers needed to run your job, VSAM terminates your job 
and provides an appropriate error message. 

When you do not specify BUFFERSPACE, VSAM determines the 
buffer space size. VSAM determines the control interval 
size first, then sets the buffer space amount equal to two 
data control intervals and one index control interval. 

When you specify BUFFERSPACE, you must specify at least 
enough space to contain two data control intervals and one 
index control interval. 

si ze 

is the amount of space to be provided for buffers. The 
value can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

Abbreviations: BUFSPC or BUFSP 

CODE(code) 

specifies a code name for the alternate index. If an 
attempt is made to access a password-protected alternate 
index without first supplying an appropriate password, a 
prompting message might be issued to the operator's console 
(see ATTEMPTS above). The prompting message includes the 
code name, which identifies the alternate index without 
revealing its entryname. 
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This parameter can be coded, but only has effect when the 
alternate-index's master password is not null. A prompting 
message is issued only when the user hasn't already 
supplied the appropriate password. 

When you don't specify a code name for the alternate index, 
the prompting message identifies the alternate index with 
i ts entryname. 

code 

can contain 1 to 8 alphameric or special characters. 
When the code contains a special character (that is, a 
comma C,3, semicolon [;], blank Cb], period [.], 
single quote ['], ampersand C&3, plus sign C+3, equal 
sign [ = 3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the code in single-quotation 
marks (for example, C0DE( 'XDORIS*' > ) . 

If the code contains a lowercase alphabetic character 
it will be folded to an uppercase alphabetic 
character. 

When the code contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, C0DE( ' *CA ' 'ROL* ' ) ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0DE(X' E2E4C5' ) is the 
same as CODE(SUE). 

CONTROLINTERVALSIZE( si ze ) 

specifies the size of the alternate-index's control 
intervals. The size of the control interval depends on the 
maximum size of data records, and on the amount of buffer 
space specified. 

When you do not specify the control interval size, VSAM 
determines the control interval size. If you have not 
specified BUFFERSPACE and the size of your records permits, 
VSAM selects the optimum size for the data control interval 
size and 512 bytes for the index control interval size. 

si ze 

for the alternate-index's data component. 

Since an alternate index always has the spanned 
attribute, the control interval size can be less than 
the maximum record length. The sizes you can 
specify — between 512 and 32,768 bytes — are a multiple 
of 512 or 2048: 

CISZ = (n x 512) or (n x 2048) 

where n is a positive integer from 1 to 16 

for the alternate-index's index component. 

You can specify the following values for the index 
component's control interval size : 

CISZ = C512 I 1024 | 2048 I 40963 

When you specify a size that is not a multiple of 512 or 
2048, VSAM chooses the next higher multiple. 

Refer to the chapter "Optimizing VSAM's Performance" in 
QS/VS Virtual Storage Access Method (VSAM) Programmer's 
Gui de for a discussion of the relationship between control 
interval size and physical block size. The discussion also 
includes restrictions that apply to control interval size 
and physical block size. 

Command Format 163 



si ze 



Abbreviations: CISZ or CNVSZ 

CONTROLPM(password) 

specifies a control password for the alternate index and 
its data and index components. The control password allows 
read and write operations against the object's control 
intervals. 

When specified as a parameter of DATA or INDEX, the control 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's control intervals (that is, the entire 
control interval, including the data portion of stored 
records and the control fields VSAM inserts into stored 
records and control intervals). 

If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon [;3, blank Cb], period [.3, 
single quote C'3, ampersand [&3, plus sign C+3, equal 
sign [=3, hyphen C-3, parenthesis C( or )3, slash [/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
C0NTR0LPW('*D0RIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, CONTROLPWC ' *CA " ROL* * ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0NTR0LPW(X' E2E4C5 ' ) 
is the same as CONTROLPW(SUE) . 

Abbreviation: CTLPW 

DESTAGEHAIT I NQDESTAGEHAIT 

specifies whether an alternate index or its component that 
is stored on a mass storage volume is to be destaged 
synchronously or asynchronously with respect to the program 
that closes it. 

DESTAGEWAIT indicates that destaging is to be completed 
before VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 

NODESTAGEWAIT indicates that notification of unsuccessful 
destaging is to be made only by a message to the operator. 

When the alternate index or component isn't stored on a 
mass storage volume, the attribute is ineffective until the 
direct access storage volume the alternate index or 
component is stored on is converted to a mass storage 
volume (by way of the CONVERTV command, which is described 
i n OS/VS Mass Storage System (MSS) Services for Reference 
Inf ormat i on ) . 

When one of these parameters is specified for the data 
component and the other parameter is specified for the 
index component, the components are destaged separately as 
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specified, except when the sequence set of the index 
component is imbedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 

Abbreviations: DSTGW and NDSTGW 

ERASEl NOERASE 

specifies whether the alternate index data component's 
records are to be erased when the alternate index is 
deleted. If ERASE is specified, the alternate index data 
component's records are overwritten with binary zeros when 
the alternate index is deleted. This attribute applies only 
to the alternate-index's data component. 

Abbreviations: ERAS and NERAS 

EXCEPTIONEXIT(entrypoint) 

specifies the name of the usei — written routine, called the 
exception exit routine, that receives control when an 
exceptional I/O error condition occurs during the transfer 
of data between your program's address space and the 
alternate-index's direct access storage space. (An 
exception is any condition that causes a SYNAD exit to be 
taken.) The component's exception-exit routine is processed 
first, then the user's SYNAD exit routine receives control. 

If an exception exit routine is loaded from an unauthorized 
library during Access Method Services processing, an 
abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter 
"Introduct i on . " 

Abbreviation: EEXT 

FILE(dname) 

names the DD statement that identifies the direct access 
device(s) and volume(s) on which space is to be allocated 
to the alternate index. When you specify UNIQUE, FILE can 
identify the DD statement which identifies and allocates 
the volumes of the alternate index. If more than one volume 
is specified in a volume list, all volumes must be the same 
device type. When the data component and index component 
are to reside on separate devices, you can specify a 
separate FILE parameter as a subparameter of DATA and INDEX 
to point to different DD statements. 

When the alternate index is defined in a recoverable 
catalog, and FILE is specified as a parameter of 
ALTERNATEINDEX, the FILE parameter can identify the DD 
statement for all volumes on which space is to be 
allocated. You also use FILE to identify the volume 
containing the base cluster's index component (when the 
base cluster is key-sequenced) or data component (when the 
base cluster is entry-sequenced) when defining into a 
recoverable catalog. When FILE refers to more than one 
volume of the same device type, the DD statement that 
describes the volumes cannot be a concatenated DD 
statement. When the alternate index is cataloged in a 
recoverable catalog, the DD statement can be concatenated 
if the volumes are a different device type: part of the 
concatenated DD statement describes the alternate index's 
or component's volumes (of one device type); the other part 
of the DD statement describes the volume that contains the 
catalog recovery area (of another device type). 

If the FILE parameter is not specified, the required 
volumes are dynamically allocated. If the alternate index 
or one of its components is unique, and if the FILE 
parameter is not specified and the volume(s) is physically 
mounted, the volume(s) identified with the VOLUMES 
parameter is dynamically allocated. The volume(s) must be 
mounted as permanently resident or reserved. 



Command Format 165 



The DD statement you specify must be in the form* 

//ddname DD UNIT=(devtype[ >uni tcountl )> 

// VOL=SER=(volserl, volser2, volser3, ...)> ... 

FREESPACECCI-percentCb CA-percent] |0 0) 

specifies the amount of space that is to be left empty 
after any allocation (that is, the initial, or primary, 
allocation and each extension, or secondary allocation) and 
any split of control intervals (Cl-percent) and control 
areas (CA-percent) when the alternate index is built (see 
the BLDINDEX command). The amount of empty space in the 
control interval and control area is available for data 
records that are updated and inserted after the alternate 
index is initially built. 

The amounts are specified as percentages. Cl-percent 
translates into a number of bytes that is equal to, or 
slightly less than, the percentage value of Cl-percent. 
CA-percent translates into a number of control intervals 
that is equal to, or less than, the percentage value of 
CA-percent. The percentages, which must be equal to or less 
than 100, can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

When you specify 100% of free space, one data record is 
placed in the first control interval of each control area 
when the alternate index is built. 

Abbreviation: FSPC 

IMBED I NOIMBED 

specifies whether the sequence set (that is, the lowest 
level of the index of the alternate index — the level that 
points to alternate-index records) is to be put adjacent to 
the alternate-index's data component. 

When you specify IMBED, the sequence-set record for each 
control area is written as many times as it will fit on the 
first track adjacent to the control area. 

The IMBED|NOIMBED parameter interacts with the 
REPLICATElNOREPLICATE parameter in determining the physical 
attributes of the index of the alternate index. These index 
attributes can be used in the following combinations-* 

• The sequence-set records are adjacent to the data 
control areas, and only the sequence-set records are 
replicated (IMBED and NOREPLICATE) . 

• The sequence-set records are adjacent to the data 
control intervals, and all levels of index records are 
replicated (IMBED and REPLICATE). 

• All index records are together, and all index records 
are replicated (REPLICATE and NOIMBED) . 

• All index records are together, and no index records 
are replicated (NOREPLICATE and NOIMBED). 

For some applications, specifying index options can improve 
the application's performance. See OS/VS Virtual Storage 
Access Method (VSAM) Programmer's Guide for information on 
how the index's optional attributes affect performance. 

Abbreviations: IMBD and NIMBD 

KEYRANGESUlowkey b highkey) 

CClowkey b highkey)...]) 

specifies that portions of the alternate-index's data 
component are to be put on different volumes. Each portion 
of the alternate index is called a key range. 
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The maximum number of alternate-key ranges is 123. Key 

ranges must be in ascending order, and aren't allowed to 

overlap. However, a gap can exist between two key 

ranges — you are not allowed to insert records within the 
gap. 

Keys can contain 1 to 64 characters; 1 to 128 hexadecimal 
characters if coded as X'lowkey' b X'highkey'. All EBCDIC 
characters are allowed. Keys consisting of characters must 
be enclosed in single quotation marks if they contain 
commas, semicolons, blanks, parentheses, or slashes. A 
single quotation mark within a key must be coded as two 
single quotation marks if the key is enclosed in single 
quotation marks. 

lowkey 

specifies the low key of the key range. If lowkey is 
shorter than the actual keys, it will be padded on the 
right with binary zeros. 

hi ghkey 

specifies the high key of the key range. If highkey is 
shorter than the actual keys, it will be padded on the 
right with binary ones. 

The KEYRANGES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure 
that, when you specify KEYRANGES, the alternate-index's 
other attributes can be satisfied. 

• V0LUMES : There should be as many volume-serial-numbers 
in the volser list as there are key ranges. When a 
volume serial number is duplicated in the volser list, 
more than one key range is allocated space on the 
volume. When more than one key range is contained on a 
volume, UNIQUE cannot be coded for the 
alternate-index's data component. 

When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key range boundaries. 

When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges are 
allocated on the last volume specified — UNIQUE cannot 
also be specified. 

• UNIQUE- When UNIQUE is specified, each key range 
resides in its own VSAM data space on a separate 
volume. Other key ranges for the alternate index cannot 
also reside on the volume. 

• ORDERED 1 There is a one-foi — one correspondence between 
the volumes in the volser list and the key ranges: the 
first volume on the volume list contains the first key 
range, the second volume contains the second key range, 
and so on. If a volume can't be allocated in the order 
specified by the volser list, your alternate index 
definition job terminates with an error message. 

• KEYS: the length of the key values must not exceed the 
key length specified in the KEYS parameter. The KEYS 
parameter must be specified in the same component as 
the KEYRANGE parameter. 

Abbreviation: KRNG 

KEYStlength b offset|64 0) 

describes the alternate-key field in the base cluster's 
data record. The key field of a key-sequenced cluster is 
called the prime key, to distinquish it from other key 
fields, called alternate keys. The data record's alternate 
key can overlap or be contained entirely within another 
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(alternate or prime) key field. 

The sum of length plus offset cannot be greater than the 
length of the base cluster's data record. 

When the base cluster's data record is allowed to span 
control intervals, the record's alternate-key field is 
within the record's first segment (that is, in the first 
control interval.) 

length b offset 

specifies the length of the alternate key (between 1 
and 255), in bytes, and i ts di splacement from the 
beginning of the base cluster's data record, in bytes. 
You can express length and offset in decimal (n), 
hexadecimal (X'n'), or binary (B'n*) form. 

MASTERPW(password) 

specifies a master password for the alternate index. The 
master password allows all Access Method Services 
operations against the alternate index entry and its data 
and index entries. The master password allows the user's 
program to access the alternate-index's contents without 
restriction. For more details on how passwords can be used, 
see "Data Security and Protection." 

If all passwords are null, ATTEMPTS, AUTHORIZATION, and 
CODE can be specified but have no effect until the master 
password is specified. 

When specified as a parameter of DATA or INDEX, the master 
password allows the user's program to open the data 
component or index component and process it without 
restri ct i on . 

When you don't specify MASTERPW, but do specify another 
password, the object's highest-level password propagates 
upward and becomes the password for all higher levels, 
including the master password. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,], semicolon C ; 3 , blank Lb3, period C.3, 
single quote ['], ampersand [&], plus sign [+], equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash E/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
MASTERPW('*DORIS*').) 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, MASTERPW( ' *CA " ROL* ' ) ) . 

YoU can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, MASTERPW(X' E2E4C5 ' ) is 
the same as MASTERPW(SUE) . 

Abbreviation: MRPW 

MODEL ( en trynameC/ password 3 

Cb catnameC/pas5word3 3 ) 

identifies an existing alternate index entry that is to be 
used as a model for the alternate index being defined. 
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When you use an alternate index entry as a model for the 
alternate index, the model alternate-index's data and index 
entries are used as models for the to-be-defined 
alternate-index's data and index components, unless another 
entry is specified with the MODEL parameter as a 
subparameter of DATA or INDEX. 

You can use an existing data entry as a model for the 
alternate-index's data component, and/or an existing index 
entry as a model for the alternate-i ndex' s i ndex component, 
without specifying a model for the alternate index itself. 

You can use some attributes of the model entry and override 
other attributes by explicitly specifying them in the 
alternate-index's definition. For details about how a model 
is used, see "How to Use One Object as a Model for Another 
Object." When you do not want to add or change any 
attributes, you specify only the entry type 
(ALTERNATEINDEX), the alternate-index's name (NAME), its 
base cluster's name (RELATE) and the model-entry's name 
(MODEL). 

entryname 

names the entry to be used as a model, entryname names 
an alternate index entry when MODEL is a parameter of 
ALTERNATEINDEX. 

entryname names an alternate-index's data entry when 
MODEL is a parameter of DATA, and it names an 
alternate-index's index entry <when MODEL is a 
parameter of INDEX. 

password 

specifies a password. If the model entry is password 
protected and i t i s cataloged in a password-protected 
catalog, you supply the read- (or higher — level) 
password of either the model entry or its catalog. If 
you supply both passwords, the catalog's password is 
used. 

If you are not specifying new protection attributes 
for the alternate index and you wish to copy the 
model's passwords and protection attributes, you must 
supply the master password of either the model entry 
or its catalog. 

catname 

names the model-entry's catalog. You must identify the 
catalog that contains the model entry when* 

♦ You want to specify tbe catalog's password instead 
of the model-entry's password. 

• The model-entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. See "Order of 
Catalog Use* DEFINE" for information about the order 
in which a catalog is selected when the catalog's name 
is not specified. 

ORDERED I UNORDERED 

specifies whether volumes are to be used in the order in 
which they are listed in the VOLUMES parameter. 

When you want each key range to reside on a separate 
volume, you can use ORDERED so that the first key range 
goes on the first volume, the second key range goes on the 
second volume, and so on. 
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If ORDERED is specified and the volumes cannot be allocated 
in the order specified, the command is terminated. 

Abbreviations: ORD and UNORD 

OWNER(owneri d) 

specifies the identification of the alternate-index's 
owner. 

owneri d 

can contain 1 to 8 EBCDIC characters. When the owneri d 
contains a special character (that is, a comma [,3, 
semicolon C ;3, blank Cb3, period C.3, single quote 
['3, ampersand [&3, plus sign [+3, equal sign [=3, 
hyphen [-3, parenthesis [( or )3, slash [/3, or 
asterisk C*3), enclose the ownerid in single-quotation 
marks (for example, 0WNER( 'XDORIS* ' ) ) . 

When the ownerid contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, 0WNER( ' *CA " ROL* ' ) ) . 

You can code ownerid in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, 0WNER(X' E2E4C5' ) is the same as 
OWNER(SUE). 

Note to TSO users: If the owner is not identified with the 
OWNER parameter, the TSO user's userid becomes the ownerid. 

READPWC password) 

specifies a read password for the alternate index or its 
data or index component. The read password permits read 
operations against the alternate-index's data records. 

When specified as a parameter of DATA or INDEX, the read 
password allows the user's program to open the data 
component or the index component for read-only processing 
of the component's data records (that is, the data portion 
of the sorted record, not the control fields VSAM inserts 
into stored records). For more details on how passwords can 
be used, see "Data Security and Protection." 

password 

i s a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb3, period [.3, 
single quote C'3, ampersand [&3, plus sign C+3, equal 
sign [=3, hyphen [-3, parenthesis [( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
READPW(' o XDORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, READPW( ' *CA "ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, READPW(X' E2E4C5 ' ) is 
the same as READPW(SUE). 

Abbreviation: RDPW 

RECORDSIZECaverage b maximuml 4086 32600) 

specifies the average and maximum length, in bytes, of an 
alternate-index record. 
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An alternate-index record can span control intervals, so 
RECORDSIZE can be larger than CONTROLINTERVALSIZE. average 
and maximum is any integer value that does not exceed the 
capacity of a control area, and can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n') form. You can 
identify the records as fixed length by specifying the same 
value for average and maximum. 

You can use the following formulas to determine the size of 
the alternate-index record when the alternate index 
supports: 

• a key-sequenced base cluster 

RECSZ = 5 + AIXKL + (n x BCKL) 

• an entry-sequenced base cluster 

RECSZ = 5 + AIXKL + (n x 4) 

where : 

RECSZ is the average record size. 

AIXKL is the alternate-key length (see the KEYS 
parameter) . 

BCKL is the base cluster's prime-key length (you 
can issue the Access Method Services LISTCAT 
command to determine the base cluster's prime-key 
length) . 

n = 1 when UNIQUEKEY is specified (RECSZ is also 
the maximum record size). 

n = the number of data records in the base cluster 
that contain the same alternate-key value, when 
NONUNIQUEKEY is specified. 

When you also specify NONUNIQUEKEY, the record size you 
specify should be large enough to allow for as many key 
pointers or RBA pointers as you anticipate. The 
record-length values apply only to the alternate-index's 
data component. 

If you plan to copy your alternate index using either the 
EXPORT or EXPORTRA command, you should be aware of the 
restriction in maximum record length imposed by these 
commands. Refer to the sections "Moving Entries" and 
"Copying a Catalog Entry From the Catalog Recovery Area" 
for details of this restriction. 

Abbreviation: RECSZ 

REPLICATE I NOREPLICATE 

specifies whether each index record (that is, each record 
in the alternate-index's index component) is to be written 
on a direct-access device track as many times as it will 
fit. 

When you specify REPLICATE, rotational delay is reduced and 
performance is improved. However, the alternate-index's 
index usually takes more direct-access device space. 

Refer to the description of the IMBED | NOIMBED parameter for 
a discussion of the relationship between IMBED | NOIMBED and 
REPLICATE | NOREPLICATE. 

Abbreviations: REPL and NREPL 

REUSE INQREUSE 

specifies whether the alternate index can be used over and 
over again as a (temporary) new alternate index. When a 
reusable alternate index is opened, its high-used RBA can 
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be set to zero if you open it with an ACB which specifies 
the RESET attribute. When you use Access Method Services 
command, BLDINDEX, to build a reusable alternate index, the 
high-used RBA is always reset to zero when the alternate 
index is opened for BLDINDEX processing. 

You cannot specify REUSE when you also specify KEYRANGES or 
UNIQUE for the alternate index or its components. Reusable 
alternate indexes may be multivolumed and are restricted to 
sixteen physical extents per volume. 

Abbreviations: RUS and NRUS 

SHAREOPTIONSCcrossregi onCb crosssystem] | 1 3) 

specifies how an alternate-index's data or index component 
can be shared among users. See OS/VS Virtual Storage Access 
Method (VSAM) Programmer's Guide for a full description of 
data-set sharing. 

Unless you specify sharing options, the alternate index 
cannot be shared. 

crossregi on 

specifies the amount of sharing allowed among regions 
(within the same system). Independent job steps in an 
operating system Can access a VSAM data set 
concurrently. To share a data set, each user must 
specify DISP=SHR in the data-set's DD statement. The 
values that can be specified are : 

1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. If a 
user desires read integrity, it is his 
responsibility to use the ENQ and DEQ macros 
appropriately to provide read integrity for the 
data hi 5 program obtains. 

3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data his program 
accesses. User programs that ignore the 
wri te-i ntegri ty guidelines can cause VSAM program 
checks, lost or inaccessible records, 
uncorrectable data-set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

specifies that the data set can be fully shared 
by any number of users, and buffers used for 
direct processing are refreshed for each request. 
This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTION 3. 

crosssystem 

specifies the amount of sharing allowed among systems. 
Job steps of two or more OS/VS operating systems can 
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gain access to the same VSAM data set regardless of 
the disposition specified in each step's DD statement 
for the data set. To get exclusive control of the 
data-set's volume* a task in one system issues the 
RESERVE macro. The level of cross-system sharing 
allowed by VSAM applies only in a multiple operating 
system environment. The values that can be specified 
are'- 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. 
With this option* each user is responsible for 
maintaining both read and write integrity for the 
data his program accesses. User programs that 
ignore wri te-i ntegri ty guidelines can cause VSAM 
program checks* uncorrectable data set failures* 
and other unpredictable results. This option 
places heavy responsibility on each user sharing 
the data set. 

specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. This option requires that you 
use the RESERVE and RELEASE macros to maintain 
data integrity while sharing the data set. 
Writing is limited to PUT-update and PUT-insert 
processing that does not change the high-used RBA 
if your program opens the data set with DISP=SHR. 
Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
environment specify DISP=SHR. Improper use of the 
RESERVE macro can cause problems similar to those 
described under SHAREOPTION 3. 

The assistance VSAM provides each user's program to 
ensure data integrity in a shared environment is : 

• Each PUT request results in the appropriate buffer 
being written immediately into the VSAM object's 
direct-access device space. VSAM writes out the 
buffer in the user's address space that contains 
the new or updated data record. 

• Each GET request results in all of the user's 
input buffers being refreshed. Each buffer's 
contents (that is* each data and index buffer 
being used by the user's program) is retrieved 
from the VSAM object's direct-access device. 

For data integrity purposes* you should make sure that 
share options specified for data and index components 
are the same. Additional information about shared data 
can be found in OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide . 

Abbreviation: SHR 

SPEED | RECOVERY 

specifies whether the data-component's control areas are 
Preformatted before alternate-index records are loaded into 
them. When RECOVERY is specified* the data-component's 
control areas are written with records that indicate 
end-of-file. When an alternate-index record is written into 
a control interval* it is always followed by a record that 
identifies the just-written record as the last record in 
the alternate index. If the initial load fails* you can 
resume loading alternate-index records after the last 

Command Format 173 



correctly-written record (because an end-of-file indicator 
identifies it as the last record — that is, no more 
alternate-index records follow). 

When SPEED is specified, the data-component f s space is not 
Preformatted. Its space might contain data records from a 
previous use of the space, or it might contain binary 
zeros — its contents are unpredictable. If the initial load 
fails, you must load the alternate-index records again from 
the beginning (because VSAM is unable to determine where 
your last correctly-written record is — VSAM cannot find a 
valid end-of-file indicator when it searches your 
alternate-index records). 

When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of-file i ndi cators, *and again with your alternate-index 
records. When you specify SPEED, your initial load is 
quicker. 

Abbreviation: RCVY 

SJAGI I BIND | CYLINDERFAULT 

specifies how an alternate index or component that is 
stored on a mass storage volume is to be staged. 

STAGE 

indicates that the alternate index or component is to 
be staged from mass storage to a direct-access storage 
staging drive when the alternate index or component is 
opened. If the alternate index or component cannot be 
staged at open time because of heavy staging activity 
of other objects, data is staged as a processing 
program needs it. 

BIND 

indicates that the alternate index or component is not 
only to be staged, but also to be bound — that is, 
retained on the direct-access storage staging drive 
until it is closed. If the alternate index or 
component cannot be staged at open time because of 
heavy staging activity of other objects, data is 
staged as a processing program needs it. 

CYLINDERFAULT 

indicates that the alternate index or component is not 
to be staged when it is opened, but that data from it 
is to be staged as a processing program needs it. 

Abbreviation: CYLF 

When the alternate index or component not stored on a mass 
storage volume, the attribute is ineffective until the 
direct-access storage volume the alternate index or 
component is stored on is converted to a mass storage 
volume (by way of the CONVERTV command, which is described 
i n OS/VS Mass Storage System (MSS) Services- Reference 
Inf ormat i on) . 

When one of these parameters is specified for the data 
component and another parameter is specified for the index 
component, the components ar& staged separately as 
specified, except when the sequence set of the index 
component is imbedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 

TO(date)lFORCdays) 

specifies the retention period for the alternate index. The 
alternate index is not automatically deleted when the 
expiration date is reached. When you do not specify a 
retention period, the alternate index can be deleted at any 
time. 
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TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the 
alternate index is to be kept before it is allowed to 
be deleted. 

FOR t days) 

specifies the number of days for which the alternate 
index is to be kept before it is allowed to be 
deleted, days can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n*) form. The maximum 
number that can be specified for days is 9999. If the 
number specified is through 1830, the retention 
period is the number of days specified. If the number 
specified is between 1831 and 9999, the retention 
period is through the year 1999. 

UNIQUE 1 SUBALLOCATIQN 

specifies whether the alternate-index's components are 
allocated an amount of space from the volume^s available 
space (UNIQUE) or from a VSAM data-space's available space 
(SUBALLOCATION.) 

When UNIQUE is specified, a VSAM data space is built and is 
assigned exclusively to each component of the alternate 
index. The data space is created when the alternate index 
is defined. The alternate-i ndex T s volume(s) must be 
mounted. VSAM builds a DSCB in the volume's table of 
contents (VTOC) to describe the data space. The name of the 
data space, which is the same as the component's name, is 
put in the DSCB. A subentry is added to the volume entry 
(in the VSAM catalog) to describe the VSAM data space. 

When SUBALLOCATION is specified, space from one of the VSAM 
data spaces on the volume is assigned to the 
alternate-index's component. 

The space-allocation attribute interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure 
that the attribute you specify for the alternate index is 
consistent with other attributes 1 

• REUSE: You cannot specify REUSE when you specify UNIQUE 
for an alternate index or its components. 

• KEYRANGES: When UNIQUE is specified, a data space is 
built and allocated on a separate volume for each key 
range. 

• VOLUMES-* When UNIQUE is not specified, VSAM data space 
must exist on the volume that is to contain the 
alternate-index's component. When UNIQUE is specified, 
and more than one volume is specified, VSAM must 
already own all the volumes except the first. If there 
is no VSAM space on a volume, you must execute a DEFINE 
SPACE CANDIDATE before your DEFINE UNIQUE. 

Abbreviations: UNQ and SUBAL 

UNIQUEKEY 1 NONUNIQUEKEY 

specifies whether more than one data record (in the base 
cluster) can contain the same alternate-key value. 

UNIQUEKEY specifies that each alternate key points to only 
one data record. When the alternate index is built (see the 
BLDINDEX command) and more than one data record contains 
the same alternate-key value, the BLDINDEX processing 
terminates with an error message. 

NONUNIQUEKEY specifies that an alternate-key value might 
point to more than one data record in the base cluster. The 
alternate-key record can point to a maximum of 32,768 
records with nonunique keys. 
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When you specify NONUNIQUEKEY, the value you specify as the 
maximum record size should be large enough to allow for 
alternate-index records that point to more than one data 
record. 

Abbreviations: UNQK and NUNQK 

UPDATEPW(password) 

specifies the update password for the alternate index or 
its data or index component. The update password permits 
read and write operations against the alternate-index's 
data records. 

When specified as a parameter of DATA or INDEX, the update 

password allows the user's program to open the data 

component or index component for read and write processing 

of the component's VSAM records (that is, the data portion 

of the stored record, not the control fields VSAM inserts 
into stored records). 

If a read password is the only password specified for the 
object (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei — level password and do not 
specify an update password, the update or read password is 
null. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,], semicolon [;3, blank Cb], period [.3> 
single quote C'3, ampersand [&], plus sign [+3, equal 
sign C=3, hyphen C-3, parenthesis [( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
UPDATEPW('*DORIS*').) 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, UPDATEPW( ' *CA ' ' ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, UPDATEPW(X' E2E4C5' ) is 
the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 

UPGRADE | NOUPGRADE 

specifies whether the alternate-index is to be upgraded 
(that is, kept up to date) when its base cluster is 
modified. UPGRADE specifies that when the base-cluster's 
records are added to, updated, or erased, the cluster's 
alternate index is upgraded to reflect the changed data. 

When UPGRADE is specified, the alternate index's name is 
cataloged with the names of other alternate indexes for the 
base cluster. The group of alternate-index names identify 
the upgrade set — all of the base cluster's alternate 
indexes that are opened when the base cluster is opened for 
write operations. 

The UPGRADE attribute is not effective for the alternate 
index until the alternate index is built (see the BLDINDEX 
command). If the alternate index is defined when the base 
cluster is open, the UPGRADE attribute takes effect the 
next time the base cluster is opened. 
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Abbreviations: UPG and NUPG 



URITECHECK I NOWRITECHECK 

specifies whether an alternate-index's data or index 
component is to be checked (by a direct-access device 
operation called write-check) when a record is written to 
the device. If WRITECHECK is specified, the record is 
written to the device, then read without data transfer to 
test for the data-check condition. 

Abbreviations: WCK and NWCK 



Components [Alternate Index) 



Attributes can be specified separately for the alternate-index's 
data and index components. 

DATA(opt i ons ) 

specifies attributes for the alternate-index's data 
component. Except for name, space allocation, and 
protection attributes, attributes specified as parameters 
of DATA override the same attributes specified as 
parameters of ALTERNATEINDEX. Attributes specified as 
parameters of DATA can also be used to override the same 
attributes of a data entry that is used as a model. 

Parameters that can be specified for the alternate-index's 
data component are'* 

• ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the data component when it is opened as 
a separate VSAM object by the user's program. 

• BUFFERSPACE* Specifies the amount of buffer space that 
the user's program is to provide from its address space 
when the program opens the data component as a separate 
VSAM object. 

• CONTROLINTERVALSIZE: Specifies the size of the data 
component's control interval. The sizes you can specify 
are J 

CISZ = (n x 512) or (n x 2048) 

where n is a positive integer from 1 to 16. 

• CYLINDERS, RECORDS, or TRACKS: Specifies an amount of 
space to be allocated to the data component. When you 
specify space as a parameter of DATA, you cannot also 
specify space for the alternate index as a whole. (See 
the description of TRACKS I CYLINDERS | RECORDS as 
parameters of ALTERNATEINDEX.) 

• DESTAGEWAIT or NODESTAGEWAIT : Specifies whether the 
data component, stored on a mass storage volume, is to 
be destaged synchronously or asynchronously with 
respect to the user's program that closes it. 

• ERASE or NOERASE* Specifies whether the data records 
are to be erased when the alternate index is deleted. 

• EXCEPTIONEXIT: Identifies an exception exit routine for 
the alternate index's data component. 

• FILE ; Names the DD statement that describes a 
direct-access device and volumes that are to contain 
the data component. When more than one volume is to 
contain the data component, all volumes must be of the 
same device type. 

• FREESPACE* Specifies the amount of space that is to be 
left free after any allocation and after any split of 
control intervals and control areas when the alternate 
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index is built (see the BLDINDEX command). 

• KEYRANGES: Specifies that portions, or key ranges, of 
the alternate index are to be put on different volumes, 
and specifies the boundaries of each key range. 

• KEYS? Describes the alternate-key field of the base 
cluster's data record. 

• MASTERPW, CONTROLPW, UPDATEPW, or READPW: Specifies 
passwords for the data component when it is opened as a 
separate VSAM object by the user's program. 

• MODEL* Identifies a data entry that is to be used as a 
model fog the data component only. 

• NAMEJ Names the data component. If you do not specify a 
name for the data component, VSAM generates one (see 
"Defining a Cluster" for the format of the generated 
name) . 

• ORDERED or UNORDERED: When ORDERED is specified, the 
volumes listed with the VOLUMES parameter are allocated 
in the order listed. 

• OWNER" Identifies the data component's owner, when the 
owner is different from the owner of the alternate 
index as a whole. 

• RECORDSIZE" Specifies the average and maximum sizes of 
the alternate-index's data records. 

• REUSE or NOREUSE"- Specifies whether the alternate 
index's data component is to be reusable. 

• SHAREOPTIONS " Specifies share options for the data 
component when it is opened as a separate VSAM object 
by the user's program. 

• STAGE, BIND, or CYLINDERFAULT * Specifies whether the 
data component, stored on a mass storage volume, is to 
be staged. 

• UNIQUE or SUBALLOCATION : Specifies whether the data 
component is to occupy exclusively a VSAM data space or 
share an existing data space with other VSAM objects. 

• UNIQUEKEY or NONUNIQUEKEY: Specifies whether more than 
one data record (in the base cluster) can contain the 
same alternate key value. 

• VOLUMES" Identifies the volume(s) that is to contain 
th« data component, and identifies other volumes that 
can be used as overflow volumes for the data component. 

• WRITECHECK or NOWRITECHECK " Specifies whether the data 
records are to be checked by the direct-access device 
when they are written into the data component. 

Restrictions are noted with each parameter's description. 
All of the DATA subparameters are described in more detail 
as parameters of the alternate index as a whole. 

INDEX(options) 

specifies attributes for the index component of an 
alternate index. 

Except for name, space allocation, and protection 
attributes, attributes specified as parameters of INDEX 
override the same attributes specified as parameters of 
ALTERNATEINDEX. Attributes specified as parameters of INDEX 
can also be used to override the same attributes of an 
index entry that is used as a model. 
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Parameters that can be specified for the alternate-i ndex 1 s 
index component arQ> 

• ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the index when it is opened as a 
separate VSAM object by the user's program. 

• CONTROLINTERVALSIZE: Specifies the index component's 
control interval size. The sizes you can specify are: 
512, 1024, 2048, or 4096 bytes. 

• CYLINDERS, RECORDS, or TRACKS: Specifies an amount of 
space to be allocated to the index component. When you 
specify one of the space-quantity parameters as a 
parameter of INDEX, you must also specify a 
space-quant i ty parameter as a parameter of DATA. You 
cannot also specify a quantity of space for the 
alternate index as a whole. 

• DESTAGEWAIT or NODESTAGEWAIT: Specifies whether the 
index component, stored on a mass storage volume, is to 
be destaged synchronously or asynchronously with 
respect to the user's program that closes it. 

• EXCEPTIONEXIT: Identifies an exception exit routine for 
the index component. 

• FILE: The DD statement describes a direct-access device 
that is to contain the index component. When more than 
one volume is to contain the index component, all 
volumes must be of the same device type. 

• IMBED or NOIMBED: Specifies whether the sequence set 
records are to be written adjacent to the data. 

• MASTERPW, CONTROLPW, UPDATEPW, or READPW: Specifies 
passwords for the index component when it is opened as 
a separate VSAM object by the user's program. 

• MODEL: Identifies an index entry that is to be used as 
a model for the index component only. 

• NAME: Names the index component. If you do not specify 
a name for the index component, VSAM generates one (see 
"Defining a Cluster" for the format of the generated 
name) . 

• ORDERED or UNORDERED: When ORDERED is specified, the 
first volume in the volser list (of the VOLUMES 
parameter) is to contain the index. Other volumes are 
to be available as overflow volumes. Otherwise, any 
volume specified in the volser list can be used for the 
index component. 

• OWNER: Identifies the index component's owner, when the 
owner identification is different from the owner of the 
alternate index as a whole. 

• REPLICATE or NOREPLICATE: Specifies whether the index 
component's records are to be repeated around the 
track. 

• REUSE or NOREUSE: Specifies whether the alternate 
index's index component is to be reusable. 

• SHAREOPTIONS: Specifies share options for the index 
component when it is opened as a separate VSAM object 
by the user's program. 

• STAGE, BIND, or CYLINDERFAULT : Specifies how the index 
component, stored on a mass storage volume, is to be 
staged. 
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• UNIQUE or SUBALLOCATION : Specifies whether the index 
component is to occupy exclusively a VSAM data space or 
share an existing data space with other VSAM objects. 

• VOLUMES: Identifies the volume that is to contain the 
index component, and identifies other volumes that can 
be used as overflow volumes for the index component. 

• WRITECHECK or NOWRITECHECK: Specifies whether the index 
component's records are to be checked by the 
direct-access device when they are written into the 
index. 

Restrictions are noted above with each parameter's 
description. All of the INDEX subparameters are described 
in more detail as parameters of the alternate index as a 
whole. 



Catalog [Alternate index) 



The catalog parameter allows you to supply the name and password 
of the catalog in which the alternate index i s to be defined. 
When you specify CATALOG, you identify the catalog that contains 
the base-cluster's entry. 

CATALOGCcatnameC/passwordl ) 

identifies the catalog in which the alternate index is to 
be defined. The catalog also contains the base cluster's 
entry (see the RELATE parameter above). See "Order of 
Catalog Use: DEFINE" for information about the order in 
which a catalog is selected if the catalog's name is not 
speci f i ed. 

catname 

specifies the catalog's name. 

password 

specifies the catalog's update or higher level 
password. If the catalog is password-protected, you 
must supply the catalog's update or higher level 
password. If no password is specified with the CATALOG 
parameter, VSAM asks the operator for the catalog's 
update password. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

If the base cluster's master password is not specified 
with the RELATE parameter, then the catalog's master 
password must be specified. 

Abbreviation: CAT 
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DEFINE ALTERNATEINDEX EXAMPLE 



Define an Alternate Index: Example 1 



In this example, an alternate index is defined. An example for 
DEFINE CLUSTER illustrates the definition of the 
alternate-index's base cluster, EXAMPLE. KSDS2 . A subsequent 
example illustrates the definition of a path, EXAMPLE. PATH, that 
allows you to process the base-cluster's data records using the 
alternate key to locate them. The alternate index, path, and 
base cluster are defined in the same catalog, AMASTCAT. 

//DEFAIX JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE ALTERNATEINDEX - 

(NAME(EXAMPLE.AIX) - 

RELATE(EXAMPLE.KSDS2) - 

MASTERPW(AIXMRPW) - 

UPDATEPU(AIXUPPW) - 

KEY5C3 0) - 

RECORDSIZEC40 50) - 

VOLUMESCVSER04) - 

CYLINDERSC3 1) - 

NONUNIQUEKEY - 

UPGRADE) - 
CATALOGCAMASTCAT/MCATUPPW) 
/x 

The job control language statement is* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE ALTERNATEINDEX command creates an alternate-index 
entry, a data entry, and an index entry to define the alternate 
index EXAMPLE. AIX. The DEFINE ALTERNATEINDEX command also 
obtains space for the alternate index from one of the VSAM data 
spaces on volume VSER04, and allocates three cylinders for the 
alternate index's use. Since the alternate index is being 
defined into a recoverable catalog, the catalog recovery volume 
will be dynamically allocated. The command's parameters are- 

• NAME, which specifies that the alternate-index's name is 
EXAMPLE. AIX. 

• RELATE, which identifies the alternate-index's base cluster, 
EXAMPLE. KSDS2. 

• MASTERPW and UPDATEPW, which specifies the alternate-index's 
master password, AIXMRPW, and update password, AIXUPPW. 

• KEYS, which specifies the length and location of the 
alternate key field in each of the base-cluster's data 
records, the alternate key field is the first three bytes of 
each data record. 

• RECORDSIZE, which specifies that the alternate-index's 
records are variable-length, with an average size of 40 
bytes and a maximum size of 50 bytes. 

• VOLUMES, which specifies that the alternate index is to 
reside on volume VSER04. This example assumes that the 
volume is already cataloged in the master catalog, AMASTCAT. 

• CYLINDERS, which specifies that three cylinders are 
allocated for the alternate-index's space. When the 
alternate index is extended, it is to be extended in 
increments of one cylinder. 
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NONUNIQUEKEY, which specifies that the alternate key value 
might be the same for two or more data records in the base 
cluster. 

UPGRADE, which specifies that the alternate index is to be 
opened by VSAM and upgraded each time the base cluster is 
opened for processing. 

CATALOG, which specifies that the alternate index is to be 
defined in the master catalog, AMASTCAT. The example also 
supplies the master catalog's update password, MCATUPPW. 
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DEFINE CLUSTER 

When you define a cluster* you can specify attributes for the 
cluster as a whole and for the cluster's components. The general 
format of the DEFINE CLUSTER command is: 

DEFINE CLUSTER (parameters) - 

CDATA(parameters) ] - 

[INDEX(parameters)3 - 

CCATALOGCsubparameters)] 
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DEFINE 



CLUSTER 

(NAME (en try name) 
{CYLINDERS(primaryCb secondary] ) I 

RECORDS(primaryCb secondary])! 

TRACKS(primary[b secondary])} 
VQLUMES(volser[b volser...]) 
CATTEHPTS(number|2)] 

CAUTHORIZATION(entrypointCb string])] 
[BUFFERSPACE(size)] 
CCODE(code)] 

[CONTROLINTERVALSIZE(sise)] 
[CONTROLPU( password)] 
[DESTAGEUAITlN ODESTAGEHAIT ] 
C ERASE 1 NOERASE ] 
CEXCEPTIONEXIT(entrypoint)] 
CFILE(dname)] 
CFREESPACE(CI-percent 

Cb CA-percent] |0 0)] 
[IMBEDl NOIHBED ] 
[INDEXED I NONINDEXED I NUMBERED] 
[KEYRANGESUlowkey b highkey) 

Cdowkey b highkey)...])] 
[KEYS (length b offsetlM 0)) 
[MASTERPW(password)] 
[ MODEL ( en tryname[/password] 

[b catname[/password] ] )] 
[ORDERED I UNORDERED ] 
[OWNER(ownerid)] 
[READPW( password)] 
[REC0RDSI2E(average b maximum)] 
[REPLICATE 1 NOREPLICATE ] 
[REUSElN OREUSE ] 
-^[SHAREOPTIONS(crossregion 

[b crosssystem] | 1 3)] 
[SPANNED 1 NOHSPANNEP ] 
[SPEED I RECOVERY ] 
[STAGE | BINDlCYLINDERFAULT ] 
[TO(date)|FOR(days)] 
[UNIQUE I SUBALLOCATION ] 
[UPDATEPW( password ) ] 
[ WRITECHECK I NOWRITECHECK] ) 



(Continued on next page.) 
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[DATA 

UATTEMPTS(number)] 

CAUTHORIZATIONCentrypointCb string] )] 

[BUFFERSPACE(size)] 

[CODE(code)] 

[CONTROLINTERVALSIZE( si ze ) ] 

[C0NTR0LPL4( password)] 

[CYLINDERS(primary[b secondary] ) | 
RECORDSCprimaryEb secondary])! 
TRACKStprimaryCb secondary])] 

CDESTAGEWAITINODESTAGEWAIT] 

[ERASEINOERASE] 

CEXCEPTIONEXITCentrypoint)] 

CFILECdname)] 

[FREESPACECCI-percentCb CA-percent] )] 

[KEYRANGE5((lowkey b highkey) 
[(lowkey b highkey)...])] 

CKEYSdength b offset)] 

CMASTERPW(password)] 

[MOD EL (entry name [/password] 
Cb catnameC/password] ) ] 

[NAME (en try name) ] 

[ORDERED | UNORDERED] 

[OWNER(ownerid)] 

[READPW( password)] 

[REC0RDSI2E(average b maximum) 

[REUSEIN0REUSE3 
— [SHAREOPTIONS(crossregion[b crosssystem] )] 

[SPANNED | NONSPANNED] 

[SPEED | RECOVERY] 

[STAGE | BIND t CYLINDERFAULT 3 

[UNIQUE | SUBALLOCATION] 

[UPDATEPW(password)] 

[VOLUMES(volser[b volser...])] 

[WRITECHECKlNOWRITECHECK])] 

r TWTJEX 

([ATTEMPTS(number)] 

[AUTHORIZATION(entrypoint[b string])] 
[CODE(code)] 

[GONTROLINTERVALSIZE( si ze ) ] 
[CONTROLPWC password)] 
[CYLINDERS(primary[b secondary] ) | 

RECORDS(primary[b secondary])! 

TRACKS(primary[b secondary])] 
[DESTAGEWAITlNODESTAGEUAIT] 
[ EXCEPTIONEXIT ( ent rypo i n t ) ] 
[FILE(dname)] 
[IMBEDjNOIMBED] 
[MASTERPW(password)] 
[ MODEL ( en tryname [/password] 

[b catname[/password] ] )] 
[ NAME ( ent ryname ) ] 
[ORDERED! UNORDERED] 
[OWNER(ownerid)] 
[READPW(password)] 
[REPLICATE | NOREPLICATE] 
[REUSEINOREUSE] 
— [SHAREOPTIONS(crossregi on[b crosssystem] )] 
[STAGE | BIND ! CYLINDERFAULT] 
[UNIQUE | SUBALLOCATION] 
[UPDATEPW(password)] 
[VOLUMES(volser[b volser...])] 
[WRITECHECKlNOWRITECHECK])] 

[CATALOG(catname[/password] )] 
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DEFINE CLUSTER Parameters: Summary 



The parameters of the DEFINE CLUSTER command can be divided into 
required and optional parameters. 

The parameters which are required for all types of clusters are>i 

• Entry type* which specifies that a cluster and its catalog 
entry are to be created (CLUSTER). 

• Name, which names the cluster (NAME). 

• Allocation, which specifies the amount of space to be 
allocated to the cluster and identifies the volume(s) that 
is to contain the cluster (VOLUMES and one of CYLINDERS, 
RECORDS, or TRACKS). You need not explicitly specify the 
allocation parameter if you specify the MODEL parameter. 

The parameters which are required for an entry-sequenced or 
relative-record cluster but are optional for a key-sequenced 
cluster are' 

• Type, which specifies the kind of data organization for the 
cluster (INDEXED, NONINDEXED, or NUMBERED). You need not 
explicitly specify the type parameter for a key-sequenced 
cluster. You need not explicitly specify the type parameter 
for an entry-sequenced or relative-record cluster if you 
specify the MODEL parameter. 

The optional parameters are : 

• Model, which identifies an existing cluster entry that is to 
be used as a model for the cluster being defined (MODEL). 

• Allocation, which specifies 

whether the cluster's data space is to be shared with 
other VSAM objects (SUBALLOCATION or UNIQUE). 

the name of the DD statement that describes the 
cluster's volume(s) (FILE). 

the size of control intervals, records, and the user 
program's buffer area (CONTROLINTERVALSIZE, RECORDSIZE, 
and BUFFERSPACE). 

how a cluster or component that i s stored on a mass 
storage device is to be staged (STAGE, BIND, or 
CYLINDERFAULT). 

whether the volume's are to be allocated in the order 
given with the VOLUMES parameter (ORDERED or UNORDERED). 

whether the cluster is intended for temporary storage of 
data (REUSE or NOREUSE) . 

whether the cluster's records can cross control-interval 
boundaries (SPANNED or NONSPANNED). 

• Data integrity, which specifies 

the name of a usei — written I/O error routine 
(EXCEPTIONEXIT). 

whether data records are to be overwritten with binary 
zeros when the cluster is deleted (ERASE or NOERASE). 

whether the data records are to be checked when the 
direct-access device writes them into secondary storage 
(WRITECHECK or NOWRITECHECK) . 

whether a cluster or component, stored on a mass storage 
volume, is to be destaged synchronously or 
asynchronously with respect to the user's program that 
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closes it (DESTAGEWAIT or NODESTAGEWAIT) . 

whether space i s to be Preformatted when the data i s 
initially loaded (RECOVERY or SPEED). 

• Protection, which 

specifies passwords for the cluster (MASTERPW, 
CONTROLPW, UPDATEPW, and READPW) . 

identifies the cluster to a console operator without 
revealing the cluster's entryname (ATTEMPTS and CODE). 

identifies a usei — wri tten-securi ty-veri f i cat i on routine 
for additional authorisation verification 
(AUTHORIZATION). 

identifies the cluster's owner (OWNER). 

specifies a retention period for the cluster (FOR or 
TO). 

• Parameters that apply only to the definition of a 
key-sequenced cluster, which specify 

whether index records are to be repeated around the 
track of the index's direct-access device (REPLICATE or 
NOREPLICATE). 

whether the index's sequence-set records are to be 
written adjacent to their data control areas (IMBED or 
NOIMBED). 

whether the data records are to be divided by key among 
volumes (KEYRANGES). 

the length and offset of the cluster's key field (KEYS). 

the amount of free space to be left in control intervals 
and control areas when the data records are loaded 
(FREESPACE). 

• Components, which specifies attributes for the cluster's 
data and, for a key-sequenced cluster, index components that 
might differ from those attributes specified for the cluster 
as a whole or the attributes established for the cluster 
being used as a model (DATA and INDEX). 

• Catalog, which identifies the catalog in which the cluster 
is to be defined (CATALOG). 

DEFINE can be abbreviated-* DEF. 
DEFINE CLUSTER PARAMETERS 

Required Parameters 

CLUSTER 

specifies that a cluster is to be defined. CLUSTER is 
followed by the parameters specified for the cluster as a 
whole; these parameters are enclosed in parentheses and, 
optionally, are followed by the DATA and/or INDEX 
parameters and their subparameters, enclosed in 
parentheses. 

Abbreviation: CL 

NAME (entryname) 

specifies the name of the entry (cluster or component) 
being defined. NAME must be specified for the cluster; it 
can optionally be specified for a data or index component. 
If no name is specified for the data or index component, a 
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name is generated. Because the cluster, data component; 
index component are individually named, each can be 
addressed. 



and 



The name may contain from 1 through 44 alphameric 
characters (A through Z, and through 9), national 
characters («>, #, and $), and two special characters (the 
hyphen and the 12-0 overpunch). Names containing more than 
eight characters must be segmented by periods; one to eight 
characters may be specified between periods. The first 
character of any name or name segment must be either an 
alphabetic or a national character. If you specify the name 
in the format entrynameCmodi f i er) , only that portion of the 
name preceding the left parenthesis will be used. The 
modifier enclosed in parentheses will be ignored. 
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Define by records will allocate sufficient space to contain 
that number of records, but variable factors unknown at 
define time (such as key compression or method of loading 
records) may result in inefficient use of the space 
allocated, preventing every data CA from being completely 
used, and causing the user to be unable to load that number 
of records without requiring secondary allocation. When 
UNIQUE is specified and the data component is to be 
contained on more than one volume, each volume can contain 
a maximum of 16 extents. 

When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
space is allocated only on the first volume when the 
component is defined. The secondary amount must be coded to 
extend the component to additional volumes. When the 
component increases in size so as to extend to additional 
volumes, the first allocation on each overflow volume is 
the primary amount. 

When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
space is immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 

secondary amounts can be allocated on all volumes available 
to contain parts of the cluster regardless of the key 
ranges. The primary and each secondary allocation must be 
able to be satisfied in 5 extents; otherwise your DEFINE or 
data set extension will fail. 

If you do not specify the MODEL parameters, you must 
specify one, and only one, of the following parameters: 
CYLINDERS, RECORDS, or TRACKS. You can specify the amount 
of space as a parameter of CLUSTER, as a parameter of DATA, 
or as a parameter of both DATA and INDEX. When a 
key-sequenced cluster is being defined and the space is 
specified as a parameter of- 

• CLUSTER, the amount specified is divided between the 
data and index components. The division algorithm is a 
function of control interval size, record size, device 
type, and other data set attributes. If the division 
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results in an allocation for the data component which 
is not an integral multiple of the required 
control-area size, the data-component's allocation is 
rounded up to the next higher control-area multiple. 
This rounding may result in a larger total allocation 
for your cluster than which you specified. 

• DATA, the entire amount specified is allocated to the 
data component. An additional amount of space, 
depending on control-interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 

When you specify UNIQUE, and the amount of space you 
specify for the data component of the cluster is not an 
even multiple of cylindei — size, VSAM rounds the allocation 
upward to a multiple of a cylinder. 

To determine the exact amount of space allocated to each 
component, list the cluster's catalog entry, using the 
LISTCAT command. 

When you specify UNIQUE, and the cluster's data space is 
the first data space on a volume that belongs to a 
recoverable catalog, an additional amount of (the 
equivalent, in tracks, of) one cylinder is allocated for 
the recovery area data space. 

pri mary 

specifies the initial amount of space that is to be 
allocated to the cluster. 

secondary 

specifies the amount of space that is to be allocated 
each time the cluster extends, as a secondary extent. 
When secondary is specified, space for the cluster's 
data and index components can be expanded to include a 
maximum of 123 extents. If the data space that 
contains (all or part of) the cluster cannot be 
extended because the cluster's secondary allocation 
amount is greater than the data-space's secondary 
allocation amount, VSAM builds a new data space. The 
new data-space's primary and secondary allocation 
amounts are equal to the cluster's secondary 
allocation amount. 

primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

Abbreviations: CYL, REC, and TRK 

VOLUMESCvolserCb volser.,.3) 

specifies the volumes to contain the cluster or component. 
VOLUMES must be specified if you do not specify the MODEL 
parameter. It can be specified for the cluster as a whole. 
Alternatively, it can be specified as a parameter of DATA 
and, if the cluster is key-sequenced, as a parameter of 
INDEX. 

If the data and index components are to reside on different 
device types, VOLUMES must be specified as both a DATA and 
an INDEX parameter. If more than one volume is listed with 
a single VOLUMES parameter, the volumes must be of the same 
device type. In a system with the Mass Storage System, a 
cluster or component can be defined on a mass storage 
volume. 

A volume serial number may be repeated in the list only if 
the INDEXED and KEYRANGE parameters are specified. You may 
wish to do this in order to have more than one key range on 
the same volume. Even in this case, repetition is only 
valid if all duplicate occurrences are used for the primary 
allocation of some key range. 
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volser 

is a 1 to 6 alphameric or national character volume 
serial number. Special characters you can specify are 
the comma [,3, semicolon [;], parentheses C( and )3, 
slash [/], asterisk [*3, period [.], single quotation 
mark t'3, ampersand [&3, plus sign [ + ], hyphen [-], 
and equal sign [ = 3. Code a single quotation mark as 
two single quotation marks. 

If the volume serial number includes a special 
character* enclose volser in quotation marks. For 
example, you can specify V0LUMES( ' VOL*10 ' 'VOL'AB') to 
include volumes VOL*10 and VOL'AB in the cluster's 
volume 1 i st . 

The VOLUMES parameter interacts with other DEFINE CLUSTER 
parameters. You should take care to ensure that the 
volume(s) you specify for the cluster can satisfy the 
cluster's other attributes- 

• SUBALLOCATION: If UNIQUE is not specified, the volume 
must contain VSAM data space. 

• KEYRANGES: If KEYRANGES and UNIQUE are specified, a 
VSAM data space is built and allocated for each key 
range on a separate volume. 

• ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-foi — one correspondence 
between the key ranges in the key-range list and the 
volumes in the volser list. 

• CYLINDERS, RECORDS, TRACKS: The volume(s) must contain 
enough unallocated space to satisfy the component's 
primary space requirement. 

• FILE: The volume information supplied with the DD 
statement(s) pointed to by FILE must be consistent with 
the information specified for the cluster and its 
components. 

• CATALOG: The data space on the volume must have been 
defined in the same catalog that the cluster is being 
defined in, and must be owned by the catalog. 

Abbreviation: VOL 



Data Organization 



When a cluster is defined, you specify whether the data is to be 
indexed (key— sequenced) , nonindexed (entry-sequenced) , or 
numbered (relative-record). 

Certain parameters apply only to key-sequenced clusters, as 
noted in the description of each of these parameters. 

If you do not specify the data organization and you also do not 
specify the MODEL parameter, your cluster will default to 
key-sequenced (indexed). If you wish to define either an 
entry-sequenced or relative-record cluster, you must specify the 
NONINDEXED or NUMBERED parameter unless you specify the MODEL 
parameter. 

INDEXED I NONINDEXED I NUMBERED 

specifies the type of data organization that the cluster is 
to have. When a cluster is defined, you can specify whether 
the data organization is to be indexed (key-sequenced), 
sequential (entry-sequenced), or numbered 

(relative-record). The data organization you select must be 
consistent with other parameters you specify. 
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INDEXED 

specifies that the cluster being defined is for 
key-sequenced data. If INDEXED is specified, an index 
component is automatically defined and cataloged. The 
data records can be accessed by key or by 
relative-byte address (RBA). See also the INDEX 
parameter. 

Abbreviation: IXD 

NONINDEXED 

specifies that the cluster being defined is for 
entry-sequenced data. The data records can be accessed 
sequentially or by relative-byte address (RBA). 

Abbreviation: NIXD 

NUMBERED 

specifies that the cluster's data organization is for 
relative-record data. A relati ve-record -cluster is 
similar to an entry-sequenced cluster, and has 
fixed-length records that are stored in slots. Each 
slot might or might not contain a data record. The 
data records are accessed by relative-record number 
(that is, slot number). 

Abbreviation: NUMD 



Optional Parameters 



ATTEMPTS(number|2) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. The number can be any number, through 7. If is 
specified* the operator is not prompted and is not allowed 
to enter a password from the console. 

number 

can be expressed in decimal (n), hexadecimal (X'n'), 
or binary (B'n') form. This parameter can be coded, 
but only has effect when the entry's master password 
is not null. A prompting message is issued only when 
the user has not already supplied the appropriate 
password. 

Note to TSO Users: At a TSO terminal* the logon password is 
checked first before the user is prompted to supply a 
password for the cluster. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the 
cluster's password because the default is 2. 

Abbreviation: att 

AUTHORIZATION(entrypointCb string]) 

specifies that a usei — security-verification routine (USVR) 
is available for additional security verification. When a 
protected cluster is accessed and the user supplies a 
correct password other than the cluster's master password, 
the USVR receives control. See OS/VS Virtual Storage Access 
Method (VSAM) Programmer's Guide for details on the USVR. 

If a USVR is loaded from an unauthorized library during 
Access Method Services processing, an abnormal termination 
will occur. See the section "Authorized Program Facility" 
in the chapter "Introduction." 

This parameter can be coded, but only has effect when the 
entry's master password is not null. 

entrypoint 

specifies the name of the user ' s-securi ty-veri f i cat i on 
routine. 
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The name can contain 1 to 8 alphameric characters (A 
through Z, or through 9), national characters (3, #, 
and $), or special characters (the hyphen and 12-0 
overpunch). The first character must be an alphabetic 
or national character. 

stri ng 

specifies information to be passed to the 
usei — security-verification routine when it receives 
control to verify authorization, and can contain 1 to 
255 EBCDIC characters. When the string contains a 
special character (that is, a comma [,3, semicolon 
[;], blank Cb3, period [.3, single quote C'3, 
ampersand C&3, plus sign [+3, equal sign [ = 3, hyphen 
C-3, parenthesis C( or )3, slash t/3, or asterisk 
[*3), enclose the string in single-quotation marks 
(for example, AUTHORIZATION entrypoint, 'XDORIS*')). 

When the string contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, AUTHORIZATION entrypoint, ' *CA» 'ROL* ' ) ) . 

You can code string in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, AUTHORIZATION(entrypoi nt, X'E2E4C5') is 
the same as AUTHORIZATION(entrypoi nt, SUE). The string 
can contain up to 255 hexadecimal characters when 
expressed in this form, resulting in up to 128 bytes 
of information. 

Abbreviation: AUTH 

BUFFERSPACE(size) 

specifies the minimum space to be provided for buffers. The 
buffer space size you specify helps VSAM determine the 
data-component's and index-component's control-interval 
size. If BUFFERSPACE is not coded, VSAM attempts to get 
enough space to contain two data component control 
intervals and, if the data is key sequenced, one 
index-component control interval. 

size 

is the amount of space to be provided for buffers, 
size can be expressed in decimal (n), hexadecimal 
(X'n*), or binary (B'n') form. The size specified 
cannot be less than enough space to contain two 
data-component control intervals and, if the data is 
key sequenced, one index control interval. If the 
specified size is less than VSAM requires for the 
buffers needed to run your job, VSAM terminates your 
DEFINE and provides an appropriate error message. 

Abbreviations: BUFSP or BUFSPC 

CODE(code) 

specifies a code name for the entry being defined. If an 
attempt i s made to access a password-protected entry 
without a password, the code name is used in a prompting 
message; the code enables the operator to be prompted for 
the password without disclosing the name of the entry. 

If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password, the operator is prompted with the 
name of the entry. 

This parameter can be coded, but only has effect when the 
cluster's or component's master password is not null. A 
prompting message is issued only when the user hasn't 
already supplied the appropriate password. 
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code 

can contain 1 to 8 alphameric or special characters. 
When the code contains a special character (that is, a 
comma [,3, semicolon t>3, blank Cb3> period C.3, 
single quote C*3, ampersand C&3, plus sign C+3 , equal 
sign [ = 3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the code in single-quotation 
marks (for example, C0DE( ' *DQRIS* ' ) ) . 

If the code contains a lowercase alphabetic character 
it will be folded to an uppercase alphabetic 
character. 

When the code contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, C0DE( ' *CA" ROL* ' ) ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0DE(X' E2E4C5 ' ) is the 
same as CODE(SUE) . 

CONTROLINTERVALSIZE(size) 

specifies the size of the control interval for the cluster 
or component. 

The size of the control interval depends on the maximum 
size of the data records and the amount of buffer space you 
provide. If the size you specify is not an integer multiple 
of 512 or 2048, VSAM selects the next higher multiple for 
your cluster's contr61-i nterval size. 

If CONTROLINTERVALSIZE is not coded, VSAM determines the 
size of control intervals. If you have not specified 
BUFFERSPACE and the size of your records permits, VSAM uses 
the optimum size for the data component and 512 for the 
index component. 

size 

for a cluster's data component. 

The size of a data-control interval must be at least 7 
bytes larger than the maximum record length if the 
data set does not have the SPANNED attribute. If the 
control interval specified is less than maximum record 
length plus the 7-byte overhead, then VSAM will 
increase the data-control interval size to contain the 
maximum record length plus the needed overhead. If the 
data set has the spanned attribute, the 
control-interval size can be less than the maximum 
record length. The sizes you can specify — between 512 
and 32,768 bytes — are an integer multiple of 512 or 
2048: 

CISZ = (n x 512) or (n x 2048) 

where n is a positive integer from 1 to 16 

for a key-sequenced cluster's index component. 

You can specify the following values: 

CISZ = C512 | 1024 | 2048 I 40963 

When you specify a size that is not a multiple of 512 or 
2048, VSAM chooses the next higher multiple. 

Refer to the chapter "Optimizing VSAM's Performance" in 
OS/VS Virtual Storage Access Method (VSAM) Programmer's 
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Gui de for a discussion of the relationship between control 
interval size and physical block size. The discussion also 
includes restrictions that apply to control interval size 
and physical block size. 

Abbreviations: CISZ or CNVSZ 

CONTROLPWCpassword) 

specifies a control password for the entry being defined. 
The control password permits operations using 
control-interval access to read, write, and update control 
intervals that contain the cluster's records. 

If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,], semicolon [;], blank [b3, period C.3, 
single quote C'3, ampersand [&]> plus sign C+3, equal 
sign C=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk [*3), enclose the password in 
single-quotation marks (for example, 
CONTROLPW('XDORISX')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, C0NTR0LPW( ' *CA" ROL* • ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0NTR0LPW(X' E2E4C5 ' ) 
is the same as CONTROLPW(SUE) . 

Abbreviation: CTLPW 

DESTAGEWAIT | NODESTAGEWAIT 

specifies whether a cluster or its component that is stored 
on a mass storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 

DESTAGEWAIT indicates that destaging is to be completed 
before VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 

NODESTAGEWAIT indicates that notification of unsuccessful 
destaging is to be made only by a message to the operator. 

When the cluster or component i s not stored on a mass 
storage volume, the attribute is ineffective until the 
di rect-access storage volume the cluster or component i s 
stored on is converted to a mass storage volume (by way of 
the CONVERTV command, which is described in OS/VS Mass 
Storage System (MSS) Services' Reference Information ) . 

When one of these parameters is specified for the data 
component and the other parameter is specified for the 
index component, the components are destaged separately as 
specified, except when the sequence set of the index 
component is imbedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 
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ERASE 1 NOERASE 

specifies whether the cluster's data component is to be 
erased when its entry in the catalog is deleted. If ERASE 
is specified* the data component is overwritten with binary 
zeros when its catalog entry is deleted. 

Abbreviations: ERAS and NERAS 

EXCEPTIONEXIT ( ent rypo i nt ) 

specifies the name of the usei — written routine, called the 
exception exit routine, that receives control when an 
exceptional I/O error condition occurs during the transfer 
of data between your program's address space and the 
cluster's direct-access storage space. (An exception is any 
I/O error condition that causes a SYNAD exit to be taken.) 
The component's exception-exit routine is processed first, 
then the user's SYNAD-exit routine receives control. 

If an exception exit routine is loaded from an unauthorized 
library during Access Method Services processing, an 
abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter 
"Introducti on." 

Abbreviation: EEXT 

FILE(dname) 

specifies the name of the DD statement that identifies the 
devices and volumes to be used for space allocation. When 
you specify UNIQUE, FILE can identify the DD statement 
which identifies and allocates the volumes of the cluster. 
If more than one volume is specified, all volumes must be 
the same device type. If data and index components are. to 
reside on different device types, FILE is specified as a 
parameter of DATA and INDEX so that separate DD statements 
can be referenced. 

When the cluster is defined in a recoverable catalog, and 
FILE is specified as a parameter of CLUSTER, the FILE 
parameter can identify the DD statement for all volumes on 
which space is to be allocated. When FILE refers to more 
than one volume of the same device type, the DD statement 
that describes the volumes cannot be a concatenated DD 
statement. When the cluster is cataloged in a recoverable 
catalog, the DD statement can be concatenated if the 
volumes are of different device types: part of the 
concatenated DD statement describes the cluster's or 
component's volume(s) of one device type; the other part of 
the DD statement describes the volume(s) of another device 
type. 

If the FILE parameter is not specified, the required 
volumes are dynamically allocated. If the cluster or one of 
its components is unique, and if the FILE parameter is not 
specified and the volume(s) is physically mounted, the 
volumeCs) identified with the VOLUMES parameter is 
dynamically allocated. The volumeCs) must be mounted as 
permanently resident or reserved. 

The DD statement you specify must be in the form : 

//ddname DD UNIT=(devtypeC>uni tcountl )> 

// VOL=SER=(volserl,volser2, volser, ...),... 

FREESPACE(CI-percentCb CA-percent] I 0) 

specifies the amount of space that is to be left free when 
the cluster is loaded and after any split of control 
intervals (CI-percent) and control areas (CA-percent). The 
amount of empty space in the control interval and control 
area is available for data records that are updated and 
inserted after the cluster is initially loaded. This 
parameter applies only to key-sequenced clusters. 
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The amounts are specified as percentages. Cl-percent 
translates into a number of bytes that is equal to, or 
slightly less than, the percentage value of Cl-percent. 
CA-percent translates into a number of control intervals 
that is equal to, or less than, the percentage value of 
CA-percent. Cl-percent and CA-percent, which must be equal 
to or less than 100, can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

When you specify FREESPACEdOO 100), one data record is 
placed in each control interval used for data and one 
control interval in each control area is used for data 
(that is, one data record is stored in each control area 
when the data set is loaded). When no FREESPACE value is 
coded, the default specifies that no free space is to be 
reserved when the data set is loaded. 

When you define the cluster using the RECORDS parameter, 
the amount of free space specified is not taken into 
consideration in the calculations to determine primary 
allocat i on . 

Abbreviation: FSPC 

IMBED 1 NOIMBED 

specifies whether the sequence set (the lowest level of the 
index) is to be placed with the data component. If IMBED is 
coded, each sequence-set record for each control area is 
written as many times as it will fit on the first track 
adjacent to the control area. This parameter applies only 
to key-sequenced clusters. 

The IMBEDjNOIMBED parameter interacts with the 
REPLICATEJNOREPLICATE parameter in determining the physical 
attributes of the index of the cluster. These index 
attributes can be used in the following combi nati ons: 

• The sequence set records are adjacent to the data 
control areas, and only the sequence set records are 
replicated (IMBED and NOREPLICATE) . 

• The sequence set records are adjacent to the data 
control intervals, and all levels of index records are 
replicated (IMBED and REPLICATE). 

• All index records are together, and all index records 
are replicated (REPLICATE and NOIMBED). 

• All index records are together, and no index records 
are replicated (NOREPLICATE and NOIMBED). 

For some applications, specifying index options can improve 
the application's performance. 

See QS/VS Virtual Storage Access Method (VSAM) Programmer's 
Gui de for information on how the index's optional 
attributes affect performance. 

Abbreviations: IMBD and NIMBD 

KEYRANGESUlowkey b highkey) 

CClowkey b highkey)...]) 

specifies that portions of key-sequenced data are to be 
placed on different volumes. Each portion of the data is 
called a key range. This parameter applies only to 
key-sequenced clusters. 

The maximum number of key ranges is 123. Key ranges must be 
in ascending order, and are not allowed to overlap. A gap 
can exist between two key ranges, but you are not allowed 
to insert records whose keys arQ within the gap. 
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The KEYRANGES parameter interacts with other DEFINE CLUSTER 
parameters. You should take care to ensure that, when you 
specify KEYRANGES, the cluster's other attributes can be 
sati sf i ed. 

• VOLUMES: There should be as many volume serial numbers 
in the volser list as there are key ranges. When a 
volume serial number is duplicated in the volser list, 
more than one key range is allocated space on the 
volume. When more than one key range is contained on a 
volume, UNIQUE cannot be coded for the cluster's data 
component. 

When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key-range boundaries. 

When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges ar& 
allocated on the last volume specified — UNIQUE cannot 
also be specified. 

• UNIQUE^ When UNIQUE is specified, each key range 
resides on its own volume in its own VSAM data space. 
Other key ranges for the cluster cannot also reside on 
the volume. 

• ORDERED: There is a one-foi — one correspondence between 
the volumes in the volser list and the key ranges: The 
first volume on the volume list contains the first key 
range, the second volume contains the second key range, 
and so on. If a volume cannot be allocated in the order 
specified by the volser list, your cluster definition 
job terminates with an error message. 

• KEYS: The length of the key values must not exceed the 
key length specified in the KEYS parameter. The KEY 
parameter must be specified in the same component as 
the KEYRANGE parameter. 

Keys can contain 1 to 64 characters; 1 to 128 hexadecimal 
characters if coded as X'lowkey' b X'highkey'. All EBCDIC 
characters are allowed. Keys consisting of characters must 
be enclosed in single quotation marks if they contain 
commas, semicolons, blanks, parentheses, or slashes. A 
single quotation mark within a key must be coded as two 
single quotation marks if the key is enclosed in single 
quotation marks. 

lowkey 

specifies the low key of the key range. If lowkey is 
shorter than the actual keys, it will be padded on the 
right with binary zeros. 

highkey 

specifies the high key of the key range. If highkey is 
shorter than the actual keys, it will be padded on the 
right with binary ones. 

Abbreviation: KRNG 

KEYSClength b offset|64 0) 

specifies information about the key field of a 
key-sequenced data set's data records. This parameter 
applies only to key-sequenced clusters. The default 
specifies a key field of 64 bytes in length, beginning at 
the first byte (byte 0) of each data record. 

length b offset 

specifies the length of the key and its displacement 
(in bytes) from the beginning of the record. The sum 
of length + offset cannot exceed the length of the 
shortest record. 
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The length of the key can be from 1 through 255 bytes, 
length and offset can be expressed in decimal (n)> 
hexadecimal (X'n')> or binary (B'n') form. 

The key field of the cluster's index is called the 
prime key to distinguish it from other key fields, 
called alternate keys. See DEFINE ALTERNATEINDEX for 
more details on how to specify alternate keys for a 
cluster. 

KEYS cannot be specified when you define an 
entry-sequenced cluster or a relative-record cluster. 
When the data record is allowed to span control 
intervals, the record's key field must be within the 
part of the record that is in the first control 
interval. 

MASTERPM(password) 

specifies a master password for the entry being defined. 
The master password allows all Access Method Services 
operations against the cluster entry and its data and index 
entries. The master password allows the user's program to 
access the cluster's contents without restriction. For more 
details on how passwords can be used, see "Data Security 
and Protection." The AUTHORIZATION, CODE, and ATTEMPTS 
parameters have no effect unless the entry has a master 
password associated with it. If MASTERPW is not specified, 
the highest-level password specified becomes the password 
for all higher levels. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma t,3, semicolon C;3, blank Cbl, period C.], 
single quote C'3, ampersand [&], plus sign [+], equal 
sign C=3, hyphen [-3, parenthesis C( or )3, slash E/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
MASTERPWCKDORISK' )). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, MASTERPW( ' *CA"R0L*' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, MASTERPW(X' E2E4C5 ' ) is 
the same as MASTERPW(SUE) . 

Abbreviation: MRPW 

KODELtentrynameC/pas5word3 

Cb catnameC/password3 3 ) 

specifies that an existing entry is to be used as a model 
for the entry being defined. You can use an existing 
cluster's entry as a model for the attributes of the 
cluster being defined. For details about how a model is 
used, see "How to Use One Object as a Model for Another 
Object." 

You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the cluster or component. If you do not want to add or 
change any attributes, you need specify only the entry-type 
(cluster, data, or index) of the model to be used and the 
name of the entry to be defined. 
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When you use a cluster entry as a model for the cluster, 
the model-cluster's data and index entries are used as 
models for the to-be-defined cluster's data and index 
components, unless another entry is specified with the 
MODEL parameter as a subparameter of DATA or INDEX. 

entryname 

specifies the name of the cluster or component entry 
to be used as a model. 

password 

specifies a password. If the model entry is password 
protected and it is cataloged in a password-protected 
catalog, you must supply the read- (or highei — level) 
password of either the model entry or its catalog. If 
both passwords are supplied, the catalog's password is 
used. 

If you are not specifying new protection attributes 
for the cluster (that is, the model's passwords and 
protection attributes are being copied), you must 
supply the master password of either the model entry 
or its catalog. 

catname 

names the model-entry's catalog. You identify the 
catalog that contains the model entry for either of 
these cases: 

• You specify the catalog's password instead of the 
model-entry ' 5 password. 

• The model-entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. See "Order of 
Catalog Use : DEFINE" for information about the order 
in which a catalog is selected when the catalog's name 
i s not speci f i ed. 

ORDERED I UNORDERED 

specifies whether volumes are to be used in the order in 
which they were listed in the VOLUMES parameter. If 
KEYRANGES is also specified, all of the records within the 
range specified by the first low-key/high-key pair are 
placed on the first volume specified in VOLUMES; all of the 
records within the second range are placed on the second 
volume? etc. If it is impossible to allocate volumes in the 
given order and ORDERED is specified, the command is 
terminated. 

Abbreviations: ORD and UNORD 

OUNERC owner id) 

specifies the identification of the cluster's owner. 

owneri d 

can contain 1 to 8 alphameric or special characters. 

If the ownerid contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the ownerid contains a special character (that 
is, a comma [,], semicolon C;3, blank Cb], period C.3, 
single fiuote C'3, ampersand C&3, plus sign C+3, equal 
sign C=j, hyphen [-3, parenthesis C( or )3, slash L/3, 
or asteri sk [* 3 ) , enclose the ownerid in 
single-quotation marks (for example, 
0WNER( f *D0RIS*').) 
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When the ownerid contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, OWNERC T *CA "ROL* ' ) ) . 

You can code ownerid in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, OWNERCX' E2E4C5 ' ) is 
the same as OWNER(SUE). 

Note to TSO Users: If the owner is not identified with the 
OWNER parameter, the TSO user's userid becomes the ownerid. 

READPWC password) 

specifies a read password for the entry being defined. The 
read password permits read operations against the cluster's 
data records. 

password 

is a 1 to 8 alphameric special character password. 

If the password contains a lowercase alphabetic 
character it is folded to an uppercase alphabetic 
character. 

When the password contains a special character (that 
is, a comma [,], semicolon C;3, blank Cb3, period [.], 
single quote C'3, ampersand C&3, plus sign [+3, equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk [*3), enclose the password in 
single-quotation marks (for example, 
READPW('*DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, READPW( ' *CA "ROL* » ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, READPW(X' E2E4C5 ' ) is 
the same as READPW(SUE). 

Abbreviation: RDPW 

RECORDSIZE(average b maximum I default ) 

specifies the average and maximum lengths, in bytes, of the 
records in the data component. 

RECORDSIZE can be specified as a parameter of either 
CLUSTER or DATA. 

average and maximum are integer values and can be expressed 
in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 
The minimum record size that you can specify is 1 byte. For 
nonspanned records, the maximum recordsize + 7 cannot 
exceed^the data-component's control interval size (that is, 
the maximum nonspanned record size, 32,761, + 7 equals the 
maximum data-component control interval size, 32,768). For 
spanned records , the maximum record size cannot exceed the 
number of control intervals per control area x (control 
interval size less ten), as calculated by VSAM. When you 
specify a record sire that is larger than one control 
interval, you must also specify spanned records (SPANNED). 

You can identify the records as fixed-length by specifying 
the same value for average and maximum. If NUMBERED is also 
specified, the records must be fixed-length (that is, 
average equals maximum). 
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When your records are fixed-length, you can use the 
following formula to find a control-interval size that 
contains a whole number (n) of records: 

CISZ = (n x RECSZ) + 10 



n = (CISZ - 10) RECSZ 
where: 

• n is the number of fixed-length records in a control 
interval, and is a positive integer. 

• CISZ is the control interval size (see also the 
CONTROLINTERVALSIZE parameter). 

• RECSZ is the average record size. 

default 

When SPANNED is specified, the default is 

RECORDSIZE(4086 32600). Otherwise, the default is 

RECORDSIZE(4089 4089). 

Caution: When you specify RECORDS, you should ensure that: 

REC(sec) x RECSZ(avg) > RECSZ(max) 

where: 

• REC(sec) is the secondary space allocation quantity, in 
records. 

• RECSZ(avg) is the average record size (default = 4086 
or 4089 bytes). 

• RECSZ(max) is the maximum record size (default = 4089 
or 32600 bytes) . 

When the SPANNED record size default prevails (32600 
bytes), the secondary allocation quantity should be at 
least 8 records. 

If you plan to copy your cluster using either the EXPORT or 
EXPORTRA command, you should be aware of the restiction in 
maximum record length imposed by these commands. Refer to 
the sections "Moving Entries" and "Copying a Catalog Entry 
From the Catalog Recovery Area" for details of this 
restri cti on . 

Abbreviation: RECSZ 

REPLICATE I NOREPLICATE 

specifies whether each index record is to be written on a 
track as many times as it will fit. When you specify 
REPLICATE, rotational delay is reduced and performance is 
improved. However, the cluster's index usually requires 
more direct-access device space. This parameter applies 
only to key-sequenced clusters. 

Refer to the description of the IMBED I NOIMBED parameter for 
a discussion of the relationship between IMBEDl NOIMBED and 
REPLICATE | NOREPLICATE. 

Abbreviations: REPL and NREPL 

REUSE 1 NOREUSE 

specifies whether the cluster can be opened again and again 
as a temporary, or reusable, cluster (that is, with its 
high-used RBA set to zero when you open it with an ACB 
which specifies the RESET attribute). REUSE allows you to 
create an entry-sequenced, key-sequenced, or 
relative-record workfile. 
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When you create a reusable cluster, you cannot build an 
alternate index to support it. Also, you cannot create a 
reusable cluster with key ranges (see the KEYRANGE 
parameter) or with its own data space (see the UNIQUE 
parameter). Reusable data sets may be multi volumed and are 
restricted to sixteen physical extents per volume. 

Abbreviations: RUS and NRUS 

SHAREOPTIONS(crossregionCb crosssystem] li 3) 

specifies how a component or cluster can be shared among 
users. See 05/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide for a description of data set sharing. 

Unless you specify sharing options, the cluster cannot be 
shared. 

crossregion 

specifies the amount of sharing allowed among regions. 
Independent job steps in an operating system can 
access a VSAM data set concurrently. To share a data 
set, each user must specify DISP=SHR in the data set's 
DD statement. The values that can be specified are* 

1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and that 
it can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it i s to be updated. If a 
user desires read integrity, it is necessary to 
use the ENQ and DEQ macros appropriately to 
provide read integrity for the data the program 
obtai ns. 

3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. User programs that ignore the write 
integrity guidelines can cause VSAM program 
checks, lost or inaccessible reccords, 
uncorrectabble data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 
This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTION 3. 

crosssystem 

specifies the amount of sharing allowed among systems. 
Job steps of two or more OS/VS operating systems can 
gain access to the same VSAM data set regardless of 
the disposition specified in each step's DD statement 
for the data set. To get exclusive control of the data 
set's volume, a task in one system issues the RESERVE 
macro. The level of cross-system sharing allowed by 
VSAM applies only in a multiple operating system 
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environment. The values that can be specified are 
1 



2 



Reserved 

Reserved 

3 

specifies that the data set can be fully shared. 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data the program accesses. User programs that 
ignore wri te~i ntegri ty guidelines can cause VSAM 
program checks, uncorrectable data set failures, 
and other unpredictable results. This option 
places heavy responsibility on each user sharing 
the data set. 

specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. This option requires that you 
use the RESERVE and RELEASE macros to maintain 
data integrity while sharing the data set. 
Writing is limited to PUT-update and PUT-insert 
processing that does not change the high-used RBA 
if your program opens the data set with DISP= 
SHR. Data set integrity cannot be maintained 
unless all jobs accessing the data set in a 
cross-system environment specify DISP=SHR. 
Improper use of the RESERVE macro can cause 
problems similar to those described under 
SHAREOPTION 3. 

The assistance VSAM provides each user of SHAREOPTION 
4 to ensure data integrity in a shared environment is : 

• Each PUT request results in the appropriate 
buffer(s) being written immediately to the VSAM 
cluster's direct-access device space (that is, the 
buffer in the user's address space that contains 
the new or updated data record, and the buffers 
that contain new or updated index records when the 
user's data is key-sequenced. ) 

• Each GET request results in all of the user's 
input buffers being refreshed. That is, each 
buffer's contents (each data and index buffer 
being used by the user's program) is retrieved 
from the VSAM cluster's direct access device. 

To ensure integrity you should be sure that share 
options specified at the DATA and INDEX levels are the 
same. 

Additional information about shared data can be found 
in OS/VS Virtual Storage Access Method (VSAM) 
Programmer' s Gui de . 

Abbreviation: SHR 

SPANNED I N0N5PANNED 

specifies whether a data record is allowed to cross 
control-interval boundaries. When the maximum length of a 
data record (as specified with RECORDSIZE) is larger than a 
control interval, the record can be contained on more than 
one control interval. To ensure that you want this to 
happen, specify SPANNED. (This allows VSAM to select a 
control interval size that is optimum for the direct-access 
device.) Otherwise, VSAM would select a larger control 
interval size that accommodates your largest record. 
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When a data record which is larger than a control interval 
is put into a cluster that allows spanned records, the 
first part of the record completely fills a control 
i nterval . Subsequent control intervals are filled until the 
record is written into the cluster. Unused space in the 
record's last control interval is not available to contain 
other data records. 

Abbreviations: SPND and NSPND 

SPEED I RECOVERY 

specifies whether storage allocated to the data component 
is to be Preformatted before records are inserted. 
SPEEDlRECOVERY applies only to initial loading. 

When RECOVERY is specified, the data component's control 
areas are written with records that indicate end-of-file. 
When a data record is written (during the initial load) 
into a control interval, it is always followed by a record 
that identifies the just-written record as the last record 
in the cluster. If the initial load fails, you can resume 
loading data records after the last correctly-written data 
record (because an end-of-file indicator identifies it as 
the last record — that is, no more data records follow). 

When SPEED is specified, the data component's space is not 
Preformatted. Its space might contain data records from a 
previous use of the space, or it might contain binary 
zeros — its contents are unpredictable. If the initial load 
fails, you must load the data records again from the 
beginning (because VSAM is unable to determine where your 
last correctly-written record is — VSAM cannot find a valid 
end-of-file indicator when it searches your data records). 

When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of-file indicators, and again with your data records. 
When you specify SPEED, your initial load is quicker. 

Abbreviation: RCVY 

STAGE I BIND 1 CYLINDERFAULT 

specifies how a cluster or component that is stored on a 
mass storage volume is to be staged. 

STAGE 

indicates that the cluster or component is to be 
staged from mass storage to a direct access storage 
staging drive when the cluster or component is opened. 
If the cluster or component cannot be staged at open 
time because of heavy staging activity of other 
objects, data is staged as a processing program needs 
it. 

BIND 

indicates that the cluster or component is not only to 
be staged, but also to be bound — that is, retained on 
the direct-access storage staging drive until it is 
closed. If the cluster or component cannot be staged 
at open time because of heavy staging activity of 
other objects, data is staged as a processing program 
needs it. 

CYLINDERFAULT 

indicates that the cluster or component is not to be 

staged when it is opened, but that data from it is to 

be staged as a processing program needs it. 

Abbreviation: CYLF 

When the cluster or component is not stored on a mass 
storage volume, the attribute is ineffective until the 
direct access storage volume the cluster or component is 
stored on is converted to a mass storage volume (by way of 
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the CONVERTV command, which is described in OS/VS Mass 
Storage System (MSS) Services' Reference Information ) . 

When one of these parameters is specified for the data 
component and another parameter is specified for the index 
component, the components are staged separately as 
specified, except when the sequence set of the index 
component is imbedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 

TO(date)|FORCdays) 

specifies the retention period for the cluster being 
defined. If neither TO nor FOR is specified, the cluster 
can be deleted at any time. 

TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day, through which the cluster being defined is to be 
kept . 

FOR(days) 

specifies the number of days for which the cluster 
being defined is to be kept. The maximum number that 
can be specified is 9999. If the number specified is 
through 1830, the cluster is retained for the number 
of days specified; if the number is between 1831 and 
9999, the cluster is retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

UNIQUE | SUBALLOCATION 

specifies whether the cluster's components are allocated 
space of their own or whether a portion of previously 
defined VSAM data space is to be used for each component. 

If UNIQUE is specified, the components of the cluster are 
allocated space separately. Their names appear in the VTOC 
of the volume(s) within a format-1 DSCB. 

If SUBALLOCATION is specified, the name of the data space, 
not of the component, appears in the VTOC. If SUBALLOCATION 
is coded, a data space must exist on the volume on which 
the cluster or components are to reside. When UNIQUE is 
specified as a parameter of CLUSTER, a data space is built 
and allocated to each component of the cluster. 

The space-allocation attribute interacts with other DEFINE 
CLUSTER parameters. You should take care to ensure that the 
attribute you specify for the cluster is consistent with 
other attributes 1 

• REUSE*. You cannot specify REUSE when you specify UNIQUE 
for a cluster or its components. 

• KEYRANGES' When UNIQUE is specified, a data space is 
built and allocated for each key range. Each key range 
i s on a separate volume. 

• VOLUMES: When UNIQUE is not specified, VSAM data space 
must exist on the volume that is to contain the 
cluster's component. When UNIQUE is specified, and more 

Hhan one volume is specified, VSAM must already own all 

the volumes except the first. If there is no VSAM space 

on a volume, you must execute a DEFINE SPACE CANDIDATE 
before your DEFINE UNIQUE. 

Abbreviations: UNQ and SUBAL 
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UPDATEPMt password) 

specifies an update password for the entry being defined. 
The update password permits read and write operations 
against the cluster's data records. 

If a read password is the only password specified for the 
object (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei — level password and do not 
specify an update password, the update password is null. 

password 

is a 1 to 8 alphameric or special chaVacter password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma t,3, semicolon t;3, blank Cb], period C.3, 
single quote C'3, ampersand I&3, plus sign t+], equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
UPDATEPW('*D0RIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, UPDATEPW( ' *CA ' * ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, UPDATEPW(X' E2E4C5 ' ) is 
the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 

WRITECHECK 1 NOURITECHECK 

specifies whether the cluster or component i s to be checked 
by a machine action called write check when a record is 
written into it. If WRITECHECK is specified, a record is 
written and then read, without data transfer, to test for 
the data check condition. 

Abbreviations: WCK and NWCK 



Components (Cluster) 



Attributes can be specified separately for the cluster's data 
and index components. 

DATA(opti ons) 

specifies attributes of the data component of the cluster. 
You can specify separate attributes for the data component 
of any type of cluster (that is, entry-sequenced, 
key-sequenced, and relative-record). 

Except for name, space allocation, and protection 
attributes, attributes specified as parameters of DATA 
override the same attributes specified as parameters of 
CLUSTER. Attributes specified as parameters of DATA also 
override the same attributes of a model cluster's data 
entry. Parameters that can be specified for the cluster's 
data component are'' 

• ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the data component when it is opened as 
a separate VSAM object by the user's program. 

• BUFFERSPACE^ Specifies the amount of buffer space that 
the user's program is to provide from its address space 
when the program opens the data component as a separate 
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VSAM object. 

CONTROLINTERVALSIZE: Specifies the size of the data 
component's control interval. The sizes you can specify 
are : 

CIS2 = (n x 512) or (n x 2048) 

where n is a positive integer from 1 to 16. 

CYLINDERS, RECORDS, or TRACKS: You can specify an 
amount of space to be allocated to the data component. 
When you specify space as a parameter of DATA, however, 
you cannot also specify space for the cluster as a 
whole. See the description of CYLINDERS I RECORDS I 
TRACKS as parameters of CLUSTER. 

DESTAGEWAIT or NODESTAGEWAIT : Specifies whether the 
data component, stored on a mass storage ..volume, is to 
be destaged synchronously or asynchronously with 
respect to the user's program that closes it. 

ERASE or NOERASE: Specifies whether the data records 
are to be erased when the cluster is deleted. 

EXCEPTIONEXIT: Identifies an exception exit routine for 
the cluster's data component. 

FILE : Names the DD statement that describes a direct 
access device and volume that is to contain the data 
component. When more than one volume is to contain the 
data component, all volumes for that component must be 
the same device type. 

FREESPACE: Specifies the amount of space that is to be 
left free during loading and after any split of control 
intervals and control areas. This parameter is valid 
only for a key-sequenced cluster. 

KEYRANGES: Specifies that portions of the data 
component of a key-sequenced cluster are to be put on 
different volumes, and specifies the boundaries of each 
key range. 

KEYS: Describes the key field of a key-sequenced 
cluster's data record. 

MASTERPW, CONTROLPW, UPDATEPW, or READPW: Specifies 
passwords for the data component when it is opened as a 
separate VSAM object by the user's program. 

MODEL: Identifies a data entry that is to be used as a 
model for the data component only. 

NAME: Names the data component. If you do not specify a 
name for the data component, VSAM generates one (see 
"Defining a Cluster" for the format of the generated 
name) . 

ORDERED or UNORDERED: When ORDERED is specified, the 
volumes listed with the VOLUMES parameter are allocated 
in the order listed. 

OWNER: Identifies the data component's owner, when the 
owner is different from the owner of the cluster as a 
whole. 

RECORDSIZE-* Specifies the average and maximum sizes of 
the cluster's data records. 

REUSE or NOREUSE: Specifies whether the data component 
is to be reusable. 
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• SHAREOPTIONS: Specifies share options for the data 
Component when it is opened as a separate VSAM object 
by the user's program. 

• SPEED or RECOVERY: Specifies whether the data control 
intervals are to be Preformatted with the end-of-file 
indicator before data records are inserted. 

• SPANNED or NONSPANNED: Specifies whether a data record 
is allowed to cross control interval boundaries. 

• STAGE, BIND, or CYLINDERFAULT: Specifies whether the 
data component* stored on a mass storage volume, is to 
be staged. 

• UNIQUE or SUBALLQCATION: Specifies whether the data 
component is to occupy a separate VSAM data space or 
share an existing data space with other VSAM objects. 

• VOLUMES** Identifies the volume that is to contain the 
data component, and identifies other volumes that can 
be used as overflow volumes for the data component. All 
volumes must be of the same device type. 

• WRITECHECK or NOWRITECHECK- Specifies whether the data 
records are to be checked by the direct access device 
when they are written into the data component. 

DATA and its subparameters can be specified for any type of 
cluster. All of the DATA subparameters are described in 
more detail as parameters of the cluster as a whole. 
Certain of the above subparameters apply only to the data 
component of a key-sequenced cluster. 

INDEXCoptions) . 

specifies attributes of the index Component of a 
key-seguenced cluster. Except for name, space allocation, 
and protection attributes, attributes specified as 
parameters of INDEX override the same attributes specified 
as parameters of CLUSTER. Attributes specified as 
parameters of INDEX also override the same attributes of a 
model cluster's index entry. 

Parameters that can be specified for the cluster's index 
component are- 

• ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the index when it is opened as a 
separate VSAM object by the user's program. 

• CONTROLINTERVALSIZE: Specifies the size of the index's 
control interval. The sizes you can specify are- 512, 
1024, 204S, or 4096 bytes. 

• CYLINDERS, RECORDS, or TRACKS: You can specify an 
amount of space to be allocated to the index component. 
When you specify one of the space-quantity parameters 
as a parameter of INDEX, you must also specify a 
space-quantity parameter as a parameter of DATA. You 
cannot also specify a quantity of space for the cluster 
as a whole . 

• DESTAGEWAIT or NODESTAGEWAIT : Specifies whether the 
index component, stored on a mass storage volume, is to 
be destaged synchronously or asynchronously with 
respect to the user's program that closes it. 

• EXCEPTIONEXIT: Identifies an exception exit routine for 
the index component. 

• FILE: The DD statement describes a direct access device 
that i s to contain the index.- When more than one volume 
is to contain the index component, all volumes for that 
component must be the same device type. 
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• IMBED or NOIMBED* Specifies whether the sequence set 
records are to be written adjacent to the data. 

• MASTERPW, CONTROL PWy UPDATEPW; or READPW: Specifies 
passwords for the index when it is opened as a separate 
VSAM object by the user's program. 

• MODEL 1 Identifies an index entry that is to be used as 
a model for the index component only. 

• NAME : Names the index component. If you do not specify 
a name for the index component, VSAM generates one (see 
"Defining a Cluster" for the format of the generated 
name) . 

• ORDERED or UNORDERED: When ORDERED is specified, the 
first volume in the volser list (of the VOLUMES 
parameter) is to contain the index. Other volumes are 
to be available as overflow volumes. Otherwise, any 
volume specified in the volser list can be used for the 
index. 

• OWNER: ., Identi f i es the index's owner, when the owner 
identification is different from the owner of the 
cluster as a whole. 

• REPLICATE or NOREPLICATE: Specifies whether the index's 
records are to be repeated around the track. 

• REUSE or NOREUSE? Specifies whether the index component 
is to be reusable. 

• SHAREOPTIONS J Specifies share options for the index 
when i t i s opened as a separate VSAM object by the 
user's program, 

• STAGE, BIND, or CYLINDERFAULT : Specifies how the index 
component, stored on a mass storage volume, is to be 
staged. 

• UNIQUE or SUBALLOCATION: Specifies whether the index is 
to occupy a separate VSAM data space or share an 
existing data space with other VSAM objects. 

• VOLUMES 1 Identifies the volume that is to contain the 
index, and identifies other volumes that can be used as 
overflow volumes for the index. All volumes must be of 
the same device type. 

• WRITECHECK or NOWRITECHECK: Specifies whether the index 
records are to be checked by the direct-access device 
when they are written into the index. 

INDEX and its subparameters can be specified only for a 
key-sequenced cluster. Other restrictions are noted with 
each parameter's description. All of the INDEX 
subparameters are described in more detail as parameters of 
the cluster as a whole. 



catalog (Cluster) 



The catalog parameter is used to supply the name and password, 
when required, of the catalog in which the cluster i s to be 
def i ned. 

CATALOG(catname[/password] ) 

identifies the catalog in which the cluster is to be 
defined. See "Order of Catalog Use: DEFINE" for information 
about the order in which catalogs sr& used. 

catname 

specifies the name of the catalog in which the entry 
is to be defined. 
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password 

specifies the catalog's password. If the catalog is 
password protected, you must supply the update- or 
highei — level password. If no password is specified, 
VSAM asks the operator for the correct password. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 
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DEFINE CLUSTER EXAMPLES 

Define a Key-sequenced Cluster: Example 1 

In this example, a key-sequenced cluster is defined. The DATA 
and INDEX parameters are specified and the cluster's data and 
index components are explicitly named. This example assumes that 
VSAM data space exists on volume VSER02. It also assumes that an 
alias name D40 has been defined for the catalog D27UCAT1. This 
naming convention causes D40.MYDATA to be cataloged in D27UCAT1. 

//DEFCLU2 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE CLUSTER - 

(NAMECD40.MYDATA) - 
VOLUMESCVSER02) - 
RECORDSdOOO 500)) - 
DATA - 

(NAME(KSDATA) - 
KEYSC15 0) - 
RECORDSIZEC250 250) - 
FREESPACEC20 10) - 
BUFFERSPACEC25000) ) - 
INDEX - 

(NAME(KSINDEX) - 
IMBED) - 
CATALOG (D27UCAT1/UPPWD27) 
/* 

The job control language statement is* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key-sequenced cluster 
D40.MYDATA. The parameters specified for the cluster as a whole 
are* 

• NAME, which specifies that the cluster's name is D40.MYDATA. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER02. 

• RECORDS, which specifies that the cluster's space allocation 
is 1,000 data records. When the cluster is extended, it is 
extended in increments of 500 records. After the space is 
allocated, VSAM calculates the amount required for the index 
and subtracts it from the total. 

In addition to the parameters specified for the cluster as a 

whole, DATA and INDEX subparameters specify values and 

attributes that apply only to the cluster's data or index 

component. The parameters specified for the data component of 
D40.MYDATA are: 

• NAME, which specifies that the data component's name is 
KSDATA. 

• KEYS, which specifies that the length of the key field is 15 
bytes and that the key field begins in the first byte (byte 
0) of each data record. 

• RECORDSIZE, which specifies fixed-length records of 250 
bytes. 

• BUFFERSPACE, which specifies that a minimum of 25000 bytes 
must be provided for I/O buffers. A large area for I/O 
buffers can help to improve access time with certain types 
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of processing. For example, with direct processing, if the 
high-level index can be kept in virtual storage, access time 
is reduced. With sequential processing, if enough I/O 
buffers are available, VSAM can perform a read-ahead thereby 
reducing system overhead and minimising rotational delay. 

• FREESPACE, which specifies that 20 percent of each control 
interval and 10 percent of each control area are to be left 
free when records are loaded into the cluster. After the 
cluster's records are loaded, the free space can be used to 
contain new records. 

The parameters specified for the index component of D40.MYDATA 
are : 

• NAME, which specifies that the index-component's name is 
KSINDEX. 

• IMBED, which specifies that sequence-set index records are 
to be placed in the data component's control areas (the 
sequence-set records will be replicated automatically). 

The parameter which provides the catalog's password is* 

• CATALOG, which specifies the catalog name and its update 
password. This parameter would not be necessary if (1) the 
catalog was not password protected and (2) D40 has been 
defined as the catalog's alias. 

Define a Key-Sequenced Cluster and an Entry-Sequenced Cluster: Example 2 

In this example, two VSAM clusters are defined. The first DEFINE 
command defines a key-sequenced VSAM cluster, D<+0 . EXAMPLE. KSDS1 . 
The second DEFINE command defines an entry-sequenced VSAM 
cluster, D50. EXAMPLE. ESDS1. In both examples it is assumed that 
alias names, D40 and D50, have been defined for user catalogs 
D27UCAT1 and D27UCAT2, respectively, and that neither user 
catalog is password protected. This example assumes that VSAM 
data space that can contain the data sets already exists on 
volumes VSER02 and VSER03. 



//DEFCLU2 


JOB 


... 




//STEP1 


EXEC PGM=IDCAMS 




//SYSPRINT 


DD 


SYS0UT=A 




//SYSIN 


DD 


X 




DEFINE CLUSTER - 








(NAMECD40. EXAMPLE. 


KSDS1) 






MODELCD40.MYDATA) 


- 






VOLUMESCVSER02) - 








NOIMBED ) 





DEFINE CLUSTER - 

(NAMECD50. EXAMPLE. ESDS1) - 
RECORD3C100 500) - 
RECORDSIZEC250 250) - 
VOLUMESCVSER03) - 
NONINDEXED ) 
/* 

The job control language statement is- 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The first DEFINE command builds a cluster entry, a data entry, 
and an index entry to define the key-sequenced cluster 
D40. EXAMPLE. KSDS1. Its parameters are: 

• NAME, which specifies the name of the key-sequenced cluster, 
D40. EXAMPLE. KSDS1. The cluster will be defined in the user 
catalog for which D40 has been established as an alias. 
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• MODEL, which identifies D40.MYDATA as the cluster to use as 
a model for D40 . EXAMPLE. KSDS1 . The attributes and 
specifications of D40.MYDATA that art* not otherwise 
specified with the DEFINE command's parameters are used to 
define the attributes and specifications of 

D40. EXAMPLE. KSDS1. D40.MYDATA is located in the user catalog 
for which D40 has been established as an alias. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER02. 

• NOIMBED, which specifies that space is not to be allocated 
for sequence-set control intervals within the 
data-component's physical extents. 

The second DEFINE command builds a cluster entry and a data 
entry to define an entry-sequenced cluster D50 . EXAMPLE. ESDS1 . 
Its parameters are: 

• NAME, which specifies the name of the entry-sequenced 
cluster, D50 .EXAMPLE. ESDS1. The cluster will be defined in 
the user catalog for which D50 has been established as an 
alias. 

• RECORDS, which specifies that the cluster's space allocation 
is 100 records. When the cluster is extended, it is entended 
in increments of 500 records. 

• RECORDSIZE, which specifies that the cluster's records are 
fixed-length (the average record size equals the maximum 
record size) and 250 bytes long. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER03. 

• NONINDEXED, which specifies that the cluster i s to be an 
entry-sequenced cluster. 

Define a Key-Sequenced Cluster (In a Unique Data Space): Example 3 

In this example, a key-sequenced cluster is defined. The cluster 
is unique; that is, it is the only cluster in a VSAM data space. 

//DEFCLU3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//V0L4 DD VOL=SER=VSER04,UNIT=2314,DISP=OLD 

//SYSIN DD x 

DEFINE CLUSTER - 

(NAME(ENTRY) - 

RECORDSIZEC80 80) - 

FILECV0L4) - 

KEYSC10 10) - 

VOLUMESCVSER04) - 

UNIQUE - 

CYLINDERSC5 10) ) - 
CATALOG(MYCAT) 
/* 

The job control language statement is'* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer arG to be sent. 

The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key-sequenced cluster ENTRY. 
The DEFINE CLUSTER command also allocates a data space and 
allocates it for the cluster's exclusive use. The command's 
parameters are : 
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NAME* which specifies the cluster's name is ENTRY. 

RECORDSIZE* which specifies that the records are 
fixed-length* 80 byte records. 

FILE* which specifies the name of a DD statement that 
describes the cluster's volume and causes it to be mounted. 
The volume must be mounted so that VSAM can record the 
format-1 DSCBs of the key-sequenced cluster in the volume's 
VTOC. If FILE is not specified* the volume is dynamically 
allocated. 

KEYS* which specifies that the length of the key field is 10 
bytes and that the key field begins in the 11th byte (byte 
10) of each data record. 

VOLUMES and UNIQUE* which specify that ENTRY is to reside 
alone in a data space on volume VSER04. Access Method 
Services will create two data spaces for the cluster** one 
for the data component* and one for the index. Both data 
spaces are to be on volume VSER04. This example assumes that 
volume VSER04 has enough available space to contain the new 
data space. This example also assumes that either the 
volume's entry is in the MYCAT catalog or that volume VSER04 
is not owned by a VSAM catalog at the beginning of the job. 

CYLINDERS* which specifies that five cylinders are allocated 
for the cluster's data space. When the cluster's data or 
index component is extended* the component is to be extended 
in increments of ten cylinders. 

CATALOG* which specifies the name of the catalog into which 
the cluster will be defined. In this example, MYCAT is not 
password protected and will be dynamically allocated. 



Define a Relative-Record cluster: Example 4 



In this example* a relative-record cluster is defined. The 
cluster is suballocated (that is* it can reside in a VSAM data 
space with other VSAM objects). Volume VSER04 does not have to 
be mounted or allocated at this time. 

//DEFCLU4 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE CLUSTER - 

(NAME(EXAMPLE.RRDSl) - 

RECORDSIZEdOO 100) - 

VOLUMES(VSER04) - 

TRACKSU0 5) - 

NUMBERED) - 
CATALOG(AMASTCAT/MCATUPPW) 
/* 

The job control language statement is : 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the relative-record cluster EXAMPLE. RRDS1 in the 
master catalog. The DEFINE CLUSTER command also obtains space 
for the cluster from one of the VSAM data spaces on volume 
VSER04* and allocates ten tracks for the cluster's use. The 
command's parameters are : 

• NAME, which specifies that the cluster's name is 
EXAMPLE. RRDS1. 
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• RECORDSIZE* which specifies that the records are 

f i xed-length, 100 byte records. Average and maximum record 
length must be equal for a relative-record data set. 

• VOLUMES* which specifies that the cluster is to reside on 
volume VSER04. This example assumes that the volume is 
already cataloged in the master catalog* AMASTCAT. 

• TRACKS* which specifies that ten tracks are allocated for 
the cluster's space. When the cluster is extended, it is to 
be extended in increments of 5 tracks. 

• NUMBERED* which specifies that the cluster's data 
organization is to be relative-record. This parameter 
overrides the INDEXED default. 

• CATALOG, which supplies the mastei — catalog's update 
password, MCATUPPW. 

Define a Reusable Entry-Sequenced Cluster: Example 5 

In this example, a reusable entry-sequenced cluster is defined. 
The cluster can be used as a temporary data set. Each time the 
cluster is opened* its high-used RBA can be reset to zero. The 
cluster is suballocated (that is, it can reside in a VSAM data 
space with other VSAM objects). 

//DEFCLU5 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 

DEFINE CLUSTER - 

(NAMECEXAMPLE.ESDS2) - 

RECORDSIZEC2500 3000) - 

SPANNED - 

VOLUMESCVSER03) - 

CYLINDER5C2 1) - 

NONINDEXED - 

REUSE - 

MASTERPWCESD2MRPW) - 

UPDATEPWCESD2UPPW) ) - 
CATAL0GCD27UCAT2/UPDD27) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services 
jobs. The SYSPRINT DD statement identifies the output device 
to which Access Method Services messages to the programmer 
are to be sent. 

The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the entry-sequenced cluster EXAMPLE. ESDS2 . The 
DEFINE CLUSTER command also obtains space for the cluster from 
one of the Class 1 VSAM data spaces on volume VSER03* and 
assigns ten tracks for the cluster's use. VSER03 does not have 
to be mounted or allocated at this time. The command's 
parameters are* 

• NAME* which specifies that the cluster's name is 
EXAMPLE. ESDS2. 

• RECORDSIZE* which specifies that the records are 
variable-length* with an average size of 2500 bytes and a 
maximum size of 3000 bytes. 

• SPANNED* which specifies that data records can cross 
control-interval boundaries. 

• VOLUMES* which specifies that the cluster is to reside on 
volume VSER03. This example assumes that the volume is 
already cataloged in the user catalog, D27UCAT2. 
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CYLINDERS* which specifies that two cylinders are allocated 
for the cluster's space. When the cluster is extended, it is 
to be extended in increments of one cylinder. 

NONINDEXED, which specifies that the cluster's data 
organi sat i on i s to be entry-sequenced. This parameter 
overrides the INDEXED parameter. 

REUSE, which specifies that the cluster is to be reusable. 
Each time the cluster i 5, opened, its high-used RBA can be 
reset to zero and it i s ef f ecti vely an empty cluster. 

MASTERPW arid UPDATEPW* which specify the master password, 
ESD2MRPW, and the update password, ESD2UPPW, for the 
cluster. 

CATALOG, which specifies that the cluster is to be defined 
in a user catalog* D27UCAT2. The example also supplies the 
user-catalog's master password, UPDD27 . 



Define a Key-sequenced Cluster; Example 6 



In this example, a key-sequenced cluster is defined. In other 
examples, an alternate index is defined over the cluster, and a 
path i s defined that relates the cluster to the alternate index. 
The cluster, its alternate index, and the path entry are all 
defined i n the same catalog, AMASTCAT. 

//DEFCLU6 JOB ... 
//STEP1 ; EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE CLUSTER - 

'= (NAMECEXAMPLE.KSDS2)) - 
DATA - 

(MASTERPWCDAT2MRPW) - 

UPDATEPWCDAT2UPPW) - 

READPUCDAT2RDP14) - 

RECORDSC500 100) - 

EXCEPTIONEXIT(DATEXIT) - 

ERASE -■":.■'■ 

FREESPACEC20 10) - 

KEYSC6 4) - 

RECORDSIZEC80 100) - 

VOLUMESCVSER04) ) ■- 
INDEX -, 

(MASTERPWCIND2MRPW) - 

UPDATEPW(IND2UPPW) - 

READPWCIND2RDPW) - 

RECORDSC300 300) - 

IMBED - ' 

VOLUMES(VSER04) ) - 
CATALOGCAMASTCAT/MCATUPPW) 
/* ".. '■'. .* 

The job control language statement is : 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE CLUSTER command bui Ids a cluster entry, a data entry, 
and an index entry to define the key-sequenced cluster 
EXAMPLE. KSDS2. The DEFINE CLUSTER command also obtains space for 
the cluster from one of the VSAM data spaces on volume VSER04, 
and allocates space separately for the cluster's data and index 
components. Si nee the cluster is being defined into a 
recoverable catalog, the catalog recovery area will be 
dynamically allocated on VSER04. 

The command's parameter that applies to the cluster is : 
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• NAME/ which specifies that the cluster's name is 
EXAMPLE. KSDS2. 

The command's parameters that apply only to the cluster's 
data-component are. enclosed in the parentheses following the 
DATA keyword: 

• MASTERPW, UPDATEPW, and READPW, which specify the data 
component's master password, DAT2MRPW, update password, 
DAT2UPPW, and read password, DAT2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to 
at least 500 records is to be allocated for the data 
component's space. When the data Component is extended, it 
is to be extended in increments of tracks equal to 100 
records. 



• EXCEPTIONEXIT, which specifies the name of the exception 
exit routine, DATEXIT, that is to be processed if an I/O 
error occurs while a data record is being processed. 

• ERASE, which specifies that the cluster's data i s to be 
erased (overwritten with binary zeros) when the cluster is 
deleted. 

• FREESPACE, which specifies the amounts of free space to be 
left in the data component's control intervals (20%) and the 
control areas (10% of the control intervals in the control 
area) when data records are loaded into the cluster. 

• KEYS, which specifies the location and length of the key 
field in each data record. The key field is 6 bytes long and 
begins in the fifth byte (byte 4) of each data record. 

• RECORDSIZE, which specifies that the cluster's records are 
variable-length, with an average size of 80 bytes and a 
maximum size of 100 bytes. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER04. Thi s example assumes that the volume is 
already cataloged in the master catalog, AMASTCAT. 

The command's parameters that apply only to the cluster's index 
component are enclosed in the parentheses following the INDEX 
keyword: 

• MASTERPW, UPDATEPW, and READPW, which specify the 
index-component's master password, IND2HRPW, update 
password, IND2UPPW, and read password, IND2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to 
at least 300 records is to be allocated for the 
index-component's space. When the index component is 
extended, it is to be extended in increments of tracks equal 
to 300 records. 

• IMBED, which specifies that the index's sequence set records 
are to be placed in the data-component's control areas (the 
sequence set records will be replicated automatically). 

• VOLUMES, which specifies that the index component is to 
reside on volume VSER04. 

The CATALOG parameter supplies the catalog's update password. 



Define an Entry-Sequenced cluster (The Cluster has a Generic Name): Example 7 

In this example, two entry-sequenced clusters are defined. Each 
has the generic name "GENERIC. x. BAKER, " where the asterisk (*) 
is replaced with a simple name that uniquely identifies each 
cluster. 
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//DEFCLU4 


JOB 


• • • 


//STEP 1 


EXEC PGM=IDCAMS 


//STEPCAT 


DD 


DSNAME=D27UCAT1,DISP=0LD 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSIN 


DD 


K 


DEFINE CLUSTER - 






(NAMECGENERIC.A.BAKER) - 






VOLUMESCVSER02) - 






RECORDSC100 100) - 






RECORDSIZEC80 80) - 






NONINDEXED ) - 




CATAL0GCD27UCAT1/MRPWD27) 



DEFINE CLUSTER - 

(NAMECGENERIC. B.BAKER) - 
MODELCGENERIC.A.BAKER D27UCAT1)) - 
CATAL0GCD27UCAT1/MRPWD27) 
/x 

The job control language statements are : 

• STEPCAT DD, which makes a catalog available for this job 
step: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The first DEFINE CLUSTER command defines an entry-sequenced 
cluster, GENERIC. A. BAKER. Its parameters are: 

• NAME, which specifies the name of the entry-sequenced 
cluster, GENERIC. A. BAKER. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER02. 

• RECORDS, which specifies that the cluster's space allocation 
is 100 records. When the cluster is extended, it is extended 
in increments of 100 records. 

• RECORDSIZE, which specifies that the cluster's records are 
fixed-length (the average record size equals the maximum 
record size) and 80 bytes long. 

• NONINDEXED, which specifies that the cluster is 
entry-sequenced. 

• CATALOG, which specifies that the cluster is to be defined 
in the D27UCAT1 catalog. The master password of D27UCAT1 is 
MRPWD27. 

The second DEFINE CLUSTER command uses the attributes and 
specifications of the previously defined cluster, 
GENERIC. A. BAKER, as a model for the to-be-defined cluster, 
GENERIC. B.BAKER. Its parameters are: 

• NAME, which specifies the name of the entry-sequenced 
cluster, GENERIC. B.BAKER. 

• MODEL, which identifies GENERIC. A. BAKER, cataloged in user 
catalog D27UCAT1, as the cluster to use as a model for 
GENERIC. B.BAKER. The attributes and specifications of 
GENERIC. A. BAKER that are not otherwise specified with the 
DEFINE command's parameters are used to define the 
attributes and specifications of GENERIC. B .BAKER. 

• CATALOG, which specifies that the cluster is to be defined 
in the D27UCAT1 catalog. The master password of D27UCAT1 is 
MRPWD27. 
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DEFINE GENERATIONDATAGROUP 



The format of the DEFINE command when it is used to define a 
generation data group is* 



DEFINE 



GENERATIONDATAGROUP 
(NAME I en try name) 
LIMIT(limit) 
[EMPTYI NOEMPTY ] 
COWNERCowneri d)] 
C SCRATCH i NOSCRATCH] 
[TO(date)|FOR(days)3) 

CCATALOGCcatnameE/password] )] 



DEFINE may be abbreviated : DEF 



DEFINE GENERATIONDATAGROUP PARAMETERS 



Required Parameters 



GENERATIONDATAGROUP 

specifies that a generation-data-group entry is to be 
defined. 

Abbreviation: GDG 

NAME C en try name) 

specifies the name of the generation data group that is 
being defined. The name may consist of 1 through 35 
alphameric characters (A through Z, and through 9), 
national characters (<&, #, and $), and two special 
characters (the hyphen and the 12-0 overpunch) . If the name 
is greater than eight characters, it is specified as a 
qualified name. A qualified name is segmented by periods; 
one to eight characters can be specified between periods. 
The first character of any name or name segment must be 
either an alphabetic or national character. 

LIMIT(limit) 

specifies the maximum number, from 1 to 255, of generation 
data sets that can be associated with the generation data 
group to be defined, number can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n') form. 

Abbreviation: LIM 



Optional Parameters 



EMPTY 1 NOEMPTY 

specifies what action is to be taken when the maximum 
number of generation data sets has been reached for the 
generation data group and another generation data set is to 
be cataloged. The disposition of the data-set's DSCB in the 
volume's VTOC is determined with the SCRATCH I NOSCRATCH 
parameter. 



EMPTY 



specifies that all the generation data sets are to be 
uncataloged when the limit is reached (that is, each 
data set's nonVSAM entry is automatically deleted from 
the catalog). 

Abbreviation: EMP 



NOEMPTY 

specifies that only the oldest generation data 
to be uncataloged when the limit is reached. 



set i s 
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Abbreviation: NEMP 

OWNERtowneri d) 

specifies the identification of the owner of the generation 
data group being defined. 

ownerid 

The ownerid may contain 1 to 8 EBCDIC characters. 

The ownerid must be enclosed in single quotation marks 
if it contains a comma, semicolon, blank, parenthesis, 
or slash. If a single quotation mark appears within 
ownerid, it must be coded as two single quotation 
marks when the ownerid is enclosed in single quotation 
marks. 

Ownerid may be coded in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
If ownerid is specified in hexadecimal, it must be 
preceded by X and be enclosed in single quotation 
marks. 

If Access Method Services is being used interactively with 
TSO to define a generation data group, and OWNER is not 
specified, the TSO userid is the default ownerid. 

SCRATCH 1 NOSCRATCH 

specifies whether a generation data set's DSCB is to be 
deleted from the volume's VTOC when the data set is 
uncataloged (that is, when its entry is deleted from the 
catalog automatically, as a result of EMPTY | NOEMPTY, or 
specifically, as a result of a usei — issued DELETE request). 
The user can override the SCRATCH | NOSCRATCH attribute when 
issuing the DELETE command. 

SCRATCH 

specifies that the generation data-set's DSCB is to be 
deleted from the volume's VTOC when it is uncataloged. 
Direct-access device space management (DADSM) removes 
the data set's DSCB from the VTOC, erases the 
data-set's space on the volume, and makes the space 
available to other system users. The generation data 
set ceases to exist. 

Note: On MSS volumes, the data set may not be 
scratched when it is automatically uncataloged, even 
when the SCRATCH option is specified. 

Abbreviation: SCR 

NOSCRATCH 

specifies that the generation data set's DSCB is not 
to be removed from the volume's VTOC when it is 
uncataloged. The data set's DSCB in the volume's VTOC 
is intact and is used to locate the data set. The data 
set can no longer be accessed through the catalog. 
However, your program can process the data set as it 
processes any other nonVSAM data sets — that is, by 
using a JCL DD statement to describe the data set and 
allocate it. 

Abbreviation: NSCR 

TO(date)|FOR(days) 

specifies the retention period for the generation data 
group being defined. 

TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day, through which the generation data group being 
defined is to be kept. 
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FOR(days) 

specifies the number of days for which the generation 
data group being defined is to be kept. This value can 
be expressed in decimal, hexadecimal, or binary. If it 
is expressed in hexadecimal or binary, it must be 
preceded by X or B and be enclosed in single quotation 
marks. The maximum number that can be specified is 
9999. If the number specified is through 1830, the 
generation data group is retained for the number of 
days specified; if the number is between 1831 and 
9999, the generation data group is retained through 
the year 1999. If neither TO nor FOR is specified, the 
generation data group can be deleted at any time- 



Catalog (Generation Data Group) 



CATALOGCcatnameCb password]) 

identifies the catalog in which the generation data group 
is to be defined. If the catalog's volume is physically 
mounted, it is dynamically allocated. The volume must be 
mounted as permanently resident or reserved. See "Order of 
Catalog Search : DEFINE" for information about the order in 
which a catalog is selected when the catalog's name is not 
speci f i ed. 

catname 

specifies the name of the catalog. 

password 

specifies the catalog's password. If the catalog is 
password protected, you must supply the update- or 
highei — level password. 

Abbreviation: CAT 
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DEFINE GENERATIONDATAGROUP EXAMPLE 

Define a Generation Data Group and a Generation Data Set Mi thin It: Example 1 

In this example, a generation data group is defined in the 
master catalog. Next, a generation data set is defined within 
the generation data group by using JCL statements. 

//DEFGDG JOB 

//STEP1 EXEC PGM=IDCAMS 

//GDGMOD DD DSNAME=GDG01 , DISP=( , KEEP) , 

// SPACE=CTRK,C0)),UNIT=2314,VOL=SER=VSER03, 

// DCB=CRECFM=FB,BLKSIZE=2000,LRECL=100) 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE GENERATIONDATAGROUP - 

(NAME(GDGOl) - 

EMPTY - 

NOSCRATCH - 

LIMITC255) ) 
/* 

//STEP2 EXEC PGM=IEFBR14 

//GDGDD1 DD DSNAME=GDG01(+1 ) , DISP=(NEW, CATLG) , 
// SPACE=CTRK,(10,5)),VOL=SER=VSER03, 
// UNIT=2314 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
/* 

The job control language statements are: 

• GDGMOD DD, which describes the generation data group. When 
the scheduler processes the DD statement, no space is 
allocated to GDG01. 

The model DSCB must exist on the generation data group's 
catalog volume. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

Because no catalog was specified in a CATALOG parameter or with 
a JOBCAT or STEPCAT DD statement, VSAM assumes all entries built 
for this command sequence are to be cataloged in the master 
catalog. 

The DEFINE GENERATIONDATAGROUP command defines a generation data 
group base catalog entry, GDG01. Its parameters are'' 

• NAME, which specifies the name of the generation data group, 
GDG01. Each generation data set in the group will have the 
name GDG01 .GxxxxVyy , where "xxxx" is the generation number 
and "yy" is the version number. 

• EMPTY, which specifies that all data sets in the group are 
to be uncataloged by VSAM when the group contains the 
maximum number of data sets (as specified by the LIMIT 
parameter and one more generation data set is added to the 
group). 

• NOSCRATCH, which specifies that, when a data set is 
uncataloged, its DSCB is not to be removed from its volume's 
VTOC. Therefore, even if a data set is uncataloged, its 
records can be accessed when it is allocated to a job step 
with the appropriate JCL DD statement. 

• LIMIT, which specifies that the maximum number of generation 
data sets in the group is 255. The LIMIT parameter is 

requi red. 
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The second step, STEP2, is used to allocate space and catalog a 
generation data set in the newly defined generation data group. 
Its job control statements are: 

• GD6DD1 DD, which specifies a generation data set in the 
generation data group. 

♦ SYSPRINT DD, which is required in all job steps. The 
SYSPRINT DD statement identifies the output device to which 
messages to the programmer ar& to be sent. 
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DEFINE NONVSAM 



The format of the DEFINE 
nonVSAM data set is : 



command when it is used to define a 



DEFINE 



NONVSAM 

(NAME (en try name) 
DEVICETYPES(devtypeCb devtype. . . ]) 
VOLUMES(volserCb volser...]) 
[FiLE5EQUENCENUMBERS( number Cb number. 
[ OWNER (ownerid)] 
[ T0( date )| FOR (days)]) 

CCATAL06(catname[/pas5word] )3 



.])] 



DEFINE may be abbreviated* DEF, 



DEFINE NONVSAM PARAMETERS 



Required Parameters 



NONVSAM 

specifies that a nonVSAM data set is to be defined. 

Abbreviation: NVSAM 

NAME (en try name) 

specifies the name of the nonVSAM data set being defined. 
The entryname is the name that appears in the catalog; it 
i s the name used in all future references to the data set. 
The entryname must be unique within the catalog in which it 
i s def i ned. 

Relative generation numbers (that is, GDGname( + D) cannot 
be used with the entryname when you use the DEFINE NONVSAM 
command to catalog a generation data set and attach it to a 
generation data group. You identify a generation data set 
with its generat i bn-data-group name (GDGname) followed by 
the data set's generation and version numbers^ 
NAME(GDGname.GxxxxVyy) . 

The name may consist of 1 through 44 alphameric characters 
(A through Z, and through 9), national characters (2, #, 
and $), and two special characters (the hyphen and the 12-0 
overpunch, X'CO'). Names containing more than eight 
characters must be segmented by periods; one to eight 
characters may be specified between periods. The f i rst 
character of any name or name segment must be either an 
alphabetic or national character. 

DEVICETYPES(devtypesCb devtype. ..] ) 

is. a required parameter that specifies the device types of 
the volumes containing the nonVSAM data set being defined. 
If the nonVSAM data set resides on different device types, 
the device types must be specified in the same order as the 
volume serial numbers listed i n the VOLUMES parameter. 

You can specify a device type for any device that is 
supported by your VS2 system. You can specify a generic 
device type (that is, 3330, 2314, etc.) or a specific unit 
address (that is, 121, 247, etc.). You can specify an 
esoteric device type (for example, SYSDA or TAPE) only if 
it has been established in the system device name table 
during system generation. 

Warning 2 When an esoteric device type is specified, the 
device type put in the catalog record is the unique device 
type generated for that unit name in the system device name 
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table during SYSGEN. This unique device type is a function 
of the order of that unit name in the Stage I SYSGEN deck. 

If the catalog is shared between systems* and if the unit 
names were not ordered the same in all Stage I SYSGEN 
decks, this device type may be different. An I/O GEN may 
also change this device type if the order of unit names in 
the Stage I SYSGEN deck is different. Allocation errors 
will result if a data set cataloged with an esoteric device 
type is referred to on a system in which the unit names 
were SYSGENed differently. See the discission of the 
SCRATCHlNOSCRATCH option of the DELETE command for a 
restriction on deleting data sets that have been defined 
with an esoteric device type. 

If the Data Facility/Device Support program product 
(5740-AM7) is installed on your system, and you expect to 
change the device type, you can code DEVICETYPESC 0000 ) and 
this field will be resolved at SUPERLOCATE, LOCATE, and 
DELETE time to the device type. This will allow you to use 
the nonVSAM data sets without having to recatalog them to 
point to the new volume. When you code DEVICETYPESC 0000 ) 
you must also code VOLUMESC ' xxxxxx' ) , or an error will 
result. 

Abbreviation: DEVT 

VOLUMEStvolserCb volser...]) 

specifies the volumes to contain the nonVSAM data set. In a 
system with the Mass Storage System, a nonVSAM data set can 
be defined on a mass storage volume. You can specify more 
than one volume serial number if the data set resides on 
many volumes. If the data set resides on magnetic tape and 
more than one file belongs to the data set on a single tape 
volume, you must repeat the volume's serial number in order 
to maintain a one-to-one correspondence between the volume 
serial numbers and the file sequence numbers. For example, 
if your nonVSAM data set is contained in the first three 
files of magnetic tape volume TAPE10, you specify • 

DEVICETYPESC2400 2400 2400) - 
VOLUMESCTAPE10 TAPE10 TAPE10) - 
FILESEQUENCENUMBERSC1 2 3) - 

volser 

can contain 1 to 6 alphameric or special characters. 

If the volser contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. When the volser contains a 
special character (that is, a comma [,], semicolon 
t;], blank Cb], period [.], single quote ['], 
ampersand [&], plus sign [ + ], equal sigYi [ = ], hyphen 
[-], parenthesis C( or')], slash [/], or asterisk 
[*]), enclose the volser in single-quotation marks 
(for example, VOLUMESC ' XDORIS' )) . 

When the volser contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, VOLUMESC 'XCA '' ROL ')) . You can code volser in 
hexadecimal form, where two hexadecimal characters 
represent one alphameric or special character. For 
example, VOLUMESCX' E2E4C5 ' ) is the same as 
VOLUMESCSUE). 

If the Data Facility/Device Support program product 
(5740-AM7) is installed on your system, and you expect to 
change the system residence volume serial number you can 
code V0LUMES( »xxxx*x« ) and this field wi 11 be resolved at 
SUPERLOCATE, LOCATE, and DELETE time to the system 



Command Format 225 



residence volume serial number. This will allow you to use 
the nonVSAM data sets without having to recatalog them to 
point to the new volume. 

Abbreviation: VOL 



Optional Parameters 



FILESEQUENCENUMBERSCnumberCb number. . . 3 ) 

specifies the file sequence number of the nonVSAM data set 
being defined. This number indicates the position of the 
file being defined with respect to other files of the tape. 
If the data set spans volumes, the file sequence number on 
each volume must be specified. The numbers must be 
specified in the same order as the volumes in the VOLUMES 
parameter. 

For example, if your nonVSAM data set is contained in the 
first three files of magnetic tape volume TAPE10, you 
speci fy ' 

DEVICETYPESC2400 2400 2400) - 
VOLUMESCTAPE10 TAPE10 TAPE10) - 
FILESEQUENCENUMBERSU 2 3) - 

number 

is a file sequence number, number can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

Abbreviation: FSEQN 

OWNER (owner id) 

specifies the identification of the nonVSAM data set. 

ownerid 

can contain 1 to 8 EBCDIC characters. When the ownerid 
contains a special character (that is, a comma C,3, 
semicolon [;3, blank Cb3, period C.3, single quote 
[ f 3, ampersand C&3, plus sign [+3, equal sign [=3, 
hyphen t>3, parenthesis C( or )3, slash C/3, or 
asterisk C*3), enclose the ownerid in single-quotation 
marks (for example, 0WNER( * *D0RIS* ' ) . 

When the ownerid contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, 0WNER( ' *CA ' 'ROL* • ) ) . 

You can code ownerid in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, 0WNER(X' E2E4C5' ) is the same as 
OWNER(SUE). 

If Access Method Services is being used interactively with 
TSO to define a nonVSAM data set, and OWNER is not 
specified, the TSO userid is the default ownerid. 

TO(date)lFORCdays) 

specifies the retention period for the nonVSAM data set 
being defined. The nonVSAM data set is not automatically 
deleted when the expiration date is reached. When you do 
not specify a retention period, the nonVSAM data set can be 
deleted at any time. 

The maximum number that can be specified for days is 9999. 
If the number specified is through 1830, the retention 
period is the number of days specified. If the number 
specified is between 1831 and 9999, the retention period is 
through the year 1999. 
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FOR(days) 

specifies the number of days for which the nonVSAM 
data set is to be kept before it is allowed to be 
deleted, days can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

TOCdate) 

specifies the date* in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the 
nonVSAM data set is to be kept before it is allowed to 
be deleted. 



Catalog (NonVSAM) 



CATALOG(catnameC/password3 ) 

identifies the catalog in which the nonVSAM data set is to 
be defined. 

See "Order of Catalog Search: DEFINE" for information about 
the order in which a catalog is selected when the catalog's 
name is not specified. 

catname 

specifies the name of the catalog in which the entry 
is to be def i ned. 

password 

specifies the catalog's password. If the catalog is 
password protected, you must supply the- update- or 
highei — level password. 

Abbreviation: CAT 
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DEFINE NONVSAM EXAMPLE 



Define a NonVSAM Data Set: Example 1 



In this example, two existing nonVSAM data sets are defined in a 
VSAM catalog, D27UCAT1. The DEFINE NONVSAM command cannot be 
used to create a nonVSAM data set because the command does not 
allocate space. 



//DEFNVS 


JOB 


... 


//STEP1 


EXEC 


PGM=IDCAMS 


//SYSPRINT 


DD 


SYS0UT=A 


//SYSIN 


DD 


X 



DEFINE NONVSAM - 

(NAMECEXAMPLE. NONVSAM) - 
DEVICETYPESC2314) - 
VOLUMESCVSER02) ) - 
CATAL0GCD27UCAT1/MRPWD27) 

DEFINE NONVSAM - 

(NAMECEXAMPLE.N0NVSAM2) - 
DEVICETYPESC2314) - 
VOLUMESCVSER02) ) - 
CATAL0GCD27UCAT1/MRPWD27) 
/* 

The job control language statement is* 

•' SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

Both DEFINE NONVSAM commands define a nonVSAM data set in 
catalog D27UCAT1. The DEFINE NONVSAM commands' parameters are: 

• NAME, which specifies the name of the nonVSAM data sets, 
EXAMPLE. NONVSAM and EXAMPLE. N0NVSAM2 . 

• DEVICETYPES, which specifies the type of devfce that 
contains the nonVSAM data sets, 2314 Direct Access Storage 
Devi ce. 

• VOLUMES, which specify the volume that contains the nonVSAM 
data sets, VSER02. 

• CATALOG, which identifies the catalog that is to contain the 
nonVSAM entries, D27UCAT1, and its update- or highei — level 
password, MRPWD27. 
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DEFINE PAGESPACE 



The format of the DEFINE command when it is used to define a 
page space i s ; 



DEFINE 



PAGESPACE 

(NAME (en try name) 
(CYLINDERS(primary)l 

RECORDS (primary) | 

TRACKS (primary )} 
VOLUME(volser) 
CATTEHPTS(number|2)] 

CAUTHORIZATION(entrypointCb string])] 
CCODE(code)] 
CCONTROLPW( password)] 
CFILE(dname)] 
[HASTERPLH password)] 
C MODEL (entrynameC /password] 

Cb catnameC/password] ] ) ] 
C OWNER ( own eri d)] 
CREADPW(password)] 
[SWAPlNOSWAP] 
[TO ( da teTTFOR ( days ) ] 
[ UNIQUE I SUBALLOCATION] 
[UPDATEPW(password)] ) 

[CATALOG(catname[/password] )] 



DEFINE PAGESPACE Paramaters: Summary 



The parameters of the DEFINE PAGESPACE can be divided into 
required and optional parameters. 

The required parameters are : 

• Entry type, which specifies that a page space and its 
catalog entry are to be created (PAGESPACE). 

• Name, which names the page space (NAME). 

• Allocation, which specifies the amount of space to be 
allocated to the page space and identifies its volume 
(VOLUMES and one of: CYLINDERS, RECORDS, or TRACKS). You 
need not explicitly specify the allocation parameters if you 
specify the MODEL parameter. 

The optional parameters are- 

• Those that apply only to the page-space data sets .(SWAP and 
NOSWAP). 

• Allocation, which specifies 

Whether the page space's data space is to be shared with 
other VSAM objects (SUBALLOCATION and UNIQUE). 

• Protection and integrity, which 

Associate passwords with the page space (MASTERPW, 
CONTROLPW, UPDATEPW, READPW) . 

Provide a mechanism by which the console operator can be 
prompted to supply a password without disclosing the 
name of the entry (CODE). 

Identify a usei — written routine for additional 
authorization verification (AUTHORIZATION). 

Identify the owner of the page space (OWNER). 
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Specify a retention period for the page space (TO and 
FOR). 

• Models which identifies an existing page-space entry from 
which attributes are to be copied (MODEL). 

• Catalog, which provides the name and password of the catalog 
in which the page space is to be defined (CATALOG). 

DEFINE can be abbreviated* DEF. 
DEFINE PAGESPACE PARAMETERS 

Required Parameters 

PAGESPACE 

specifies that a page space is to be defined. 

Abbreviation: PGSPC 

NAME(entryname) 

specifies the name of the entry being defined. 

The name may contain from 1 through 44 alphameric 
characters (A through Z, and through 9), national 
characters (3, #, and $), and two special characters (the 
hyphen and the 12-0 overpunch) . Names containing more than 
eight characters must be segmented by periods* one to eight 
characters may be specified between periods. The first 
character of any name or name segment must be either an 
alphabetic or national character. If you specify the name 
in the format entryname(modi f i er) , only that portion of the 
name preceding the left parenthesis will be used. The 
modifier enclosed in parentheses will be ignored. 

CYLINDERS(primary)| 

RECORDSCprimary) I 

TRACKStprimary) 

specifies the amount of space that is to be allocated by 
tracks, cylinders, or number of records. If RECORDS or 
TRACKS is specified, the quantity specified is rounded up 
to the nearest cylinder and the space is allocated in 
cyli nders. 

If you do not specify the MODEL parameter, you must specify 
one, and only one, of the following parameters* CYLINDERS, 
RECORDS, or TRACKS. 

To determine the exact amount of space allocated, list the 
page space's catalog entry, using the LISTCAT command. 

When you specify UNIQUE, and the page space's data space is 
the first data space on the volume that belongs to a 
recoverable catalog, an additional amount of (the 
equivalent, in tracks, of) one cylinder is allocated for 
the recovery area data space. 

primary 

specifies the amount of space that is to be allocated 
to the page space. Once the primary extent is full, 
the page space is full. The page space cannot extend 
onto secondary extents. 

primary can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n*) form. 

The Auxiliary Storage Manager (ASM) uses a halfword 
field to contain a relative paging slot (record) 
number within a given page space (data set). As such, 
the theoretical maximum number of paging slots for 
each page space is 65,535. This limitation currently 
affects only page space allocations on a 3350 device. 
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The maximum usable page space on a 3350 is 504 
cylinders* which is 15*120 tracks, or 65,520 slots. 

Abbreviations: CYL, REC, and TRK 

VOLUMESCvolser) 

specifies the volume that contains the page space. 

In a system with the Mass Storage System, a page space 
cannot reside on a mass storage volume. Also, a page space 
with the SWAP attribute cannot be defined on a 2314 direct 
access drive. 

volser 

can contain 1 to 6 alphameric or special characters. 

If the volser contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the volser contains a special character (that is, 
a comma [,], semicolon C;], blank Cb3, period [.3, 
single quote C f 3, ampersand C&3, plus sign C+3, equal 
sign C=3, hyphen C-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the volser in 
single-quotation marks (for example, VOLUMES 
('XDORIS*')). 

When the volser contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two si nqle-quotat i on marks (for 
example, VOLUMES ( ' *CA ' * ROL ' . ) 

You can code volser in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, VOLUMES (X'E2E4C5') is 
the same as VOLUMES (SUE).) 

You must specify the VOLUMES parameter unless you specify 
the MODEL parameter. The VOLUMES parameter interacts with 
other DEFINE PAGESPACE parameters. You should take care to 
ensure that the volume(s) you specify for the page space 
can satisfy the page space's other attributes 2 

• SUBALLOCATION: If suballocati on is specified, the 
volume must contain a VSAM data space. 

• CYLINDERS, RECORDS, TRACKS: The volume must contain 
enough unallocated space to satisfy the page space's 
space requirement. 

• FILE* The volume information supplied with the DD 
statement pointed to by FILE must be consistent with 
the information specified for the page space. 

• CATALOG? If the page space is suballocated, the data 
space on the volume must have been defined in the same 
catalog that the page space is being defined in, and 
must be owned by the catalog. 

Abbreviation: VOL 
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ATTEMPTS(number|2) 

specifies the maximum number of times the operator or TSO 
terminal user can try to enter a correct password in 
response to a prompting message. The number can be any 
number, through 7. When you define a page space, you 
should specify ATTEMPTS(O), so that the operator is not 
prompted and is not allowed to enter a password from the 
console. 
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number 

can be expressed in decimal (n), hexadecimal (X'n'), 
or bi nary (B'n' ) form. Thi s parameter can be coded* 
but only has effect when the entry's master password 
is not null. A prompting message is issued only when 
the user has not already supplied the appropriate 
password. 

Note to TSO users: At a TSO terminal, the logon 
password is checked first before the user is prompted 
to supply a password for the page space. Checking the 
logon password counts as one attempt to obtain a 
password. If ATTEMPTS is not specified, the user has 
one attempt to supply the page-space's password 
because the default is 2. 

Abbreviation: ATT 

AUTHORIZATIONCentrypointCb string]) 

specifies that a usei — security-verification routine 
(USVR) is available for additional security 
verification. When a protected page space is accessed 
and the user supplies a correct password other than 
the page-space's master password, the USVR receives 
control. 

See OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide for details on the USVR. 

If a USVR is loaded from an unauthorized library 
during Access Method Services processing, an abnormal 
termination will occur. See the section "Authorised 
Program Facility" in the chapter "Introduction." 

This parameter can be coded, but only has effect when 
the entry's master password is not null. 

entrypoi nt 

specifies the name of the 

user ' s-securi ty-veri f i cat i on routine. 

The name can contain 1 to 8 alphameric characters 
(A through Z, and through 9), national 
characters (2), #, and $), or special characters 
(the hyphen and 12-0 overpunch). The first 
character must be an alphabetic or national 
character. 

stri ng 

specifies information to be passed to the 
user-securi ty-veri fi cat i on routi ne when it 
receives control to verify authorization, and can 
contain 1 to 255 EBCDIC characters. When the 
string contains a special character (that is, a 
comma [,], semicolon I;], blank Cb3, period E.3, 
single quote ['], ampersand [&3, plus sign C+3, 
equal sign C=3, hyphen [-3, parenthesis £( or )3, 
slash [/]> or asterisk C*3), enclose the string 
in single-quotation marks (for example, 
AUTHORIZATION (entrypoint, '*D0RIS*')). 

When the string contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation 
marks (for example, AUTHORIZATION(entrypoi nt , 
'*CA' f R0L*')). 

You can code string in hexadecimal form, where 
two hexadecimal characters represent one EBCDIC 
character. For example, AUTHORIZATION(entrypoi nt, 
X»E2E4C5') is the same as 
AUTHORIZATION(entrypoint,SUE). The string can 
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contain up to 255 hexadecimal characters when 
expressed in this form, resulting in up to 128 
bytes of information. 

Abbreviation: AUTH 

CODEC code) 

specifies a code name for the page space. If an 
attempt i s made to access a password-protected entry 
without a password, the code name is used in a 
prompting message; the code enables the operator or 
TSO terminal user to be prompted for the password 
without disclosing the name of the entry. If code is 
not specified and an attempt is made to access a page 
space entry that is password protected without 
supplying a password, the operator or TSO terminal 
user is prompted with the name of the entry. 

This parameter can be coded, but only has effect when 
the cluster's or component's master password is not 
null. A prompting message is issued only when the user 
has not already supplied the appropriate password. 

code 

can contain 1 to 8 alphameric or special 
characters. When the code contains a special 
character (that is, a comma [,3, semicolon C;3, 
blank Cb3, period C.3, single quotation mark ['3, 
ampersand [&3, plus sign [+3, equal sign [=3, 
hyphen [-3, parenthesis C( or )3, slash C/3, or 
asteri sk [*3 ) , enclose the code in 
single-quotation marks (for example, 
C0DE('*D0RIS*')). 

If the code contains a lowercase alphabetic 
character it is folded to an uppercase alphabetic 
character. 

When the code contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation 
marks (for example, C0DE( ' *CA * f ROL* ' ) ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric 
or special character. For example, 
C0DE(X'E2E4C5' ) is the same as CODE(SUE). 

CONTROLPWt password) 

specifies a control-level password for the page space. 
Because the page space is a system data set, it cannot 
be opened or used by a user's program. 

If a read or update password i s the only password 
specified for the page space, it (the highest-level 
password) propagates upward and becomes the password 
for all higher unspecified levels. 

the passwords are cataloged in both the page-space 
entry and i ts data-component ' s entry. You should 
specify control-, update-, and read-level passwords to 
prevent the page space from being accessed if its 
volume i s moved to a VS1 system. A VS2 system 
automatically prevents users from accessing page 
spaces and their data components. 

password 

is a 1 to 8 alphameric or special character 
password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 
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When the password contains a special character 
(that is* a comma C,3, semicolon [;3, blank Lb], 
period C.3, single quote C'3, ampersand C&3, plus 
sign [ + 3, equal sign [=3, hyphen [-3, parenthesis 
[( or )3, slash L/3, or asterisk C*3), enclose 
the password in single-quotation marks (for 
example, C0NTR0LPW( » *D0RIS* ' ) ) . 



When the password contains a special 
and also contains a single-quotation 
the imbedded quotation mark as two 
single-quotation marks (for example, 
C0NTR0LPW( »*CA» 'ROL*' ) ) . 



character 
mark, code 



You can code password in hexadecimal form, where 
two hexadecimal characters represent one 
alphameric or special character. For example, 
C0NTR0LPW(X'E2E4C5') is the same as 
CONTROLPW(SUE). 

Abbreviation: CTLPW 

FILE(dname) 

specifies the name of the DD statement that identifies 
the device and volume to be allocated to the page 
space. If the page space is unique, and if the FILE 
parameter is not specified and the volume is 
physically mounted, the volume identified with the 
VOLUME parameter is dynamically allocated. The volume 
must be mounted as permanently resident or reserved. 

MASTERPW(password) 

specifies a master password for the page space. The 
master password allows all Access Method Services 
operations against the page space entry. The 
AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password 
associated with it. If MASTERPW is not specified, the 
highest level password specified becomes the password 
for all higher levels. Because the page space is a 
system data set, it cannot be opened or used by a 
user's program. 

The passwords are cataloged in both the page-space 
entry and its data-component's entry. You should 
specify control-, update-, and read-level passwords to 
prevent the page space from being accessed if its 
volume is moved to a VS1 system. A VS2 system 
automatically prevents users from accessing page 
spaces and their data components. 



password 

is a 1 to 8 alphameric 
password. 



or special character 



If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character 
(that is, a comma [,3, semicolon [;3, blank Eb3, 
period [.3, single quote C'3, ampersand C&3, plus 
sign C+3, equal sign [=3, hyphen E-3, parenthesis 
[(or )3, slash C/3, or asterisk C*3), enclose 
the password in single-quotation marks (for 
example, MASTERPW( '*D0RIS* ' ) ) . 

When the password contains a special character 
and also contains a single-quotation mark, code 
the imbedded quotation mark as two 
single-quotation marks (for example, 
MASTERPW('*CA"R0L*')). 
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You can code password in hexadecimal form, where 
two hexadecimal characters represent one 
alphameric or special character. For example, 
MASTERPW(X'E2E4C5') is the same as MASTERPW(SUE) . 

Abbreviation: MRPW 

MODEL (entry name [/pa s swordl 

Cb catnamet/password] 3 ) 

specifies that an existing page space entry is to be 
used as a model for the entry being defined. It is 
possible to use an already defined page space as a 
model for another page space. When one entry is used 
as a model for another, its attributes are copied as 
the new entry is defined. 

For more details on how a model is used, see "How to 
Use One Object as a Model For Another Object." 

You may use some attributes of the model and override 
others by explicitly specifying them in the definition 
of the page space. If you do not want to add or change 
any attributes, you need specify only the entry-type 
(page space) of the model to be used and the name of 
the entry to be defined. 

entryname 

specifies the name of the page space entry to be 
used as a model. 

password 

specifies a password. If the entry to be used as 
a model is password protected and is cataloged in 
a password-protected catalog, a password is 
required. If the protection attributes ar& to be 
copied, substitute the master password of either 
the entry being used as a model (following 
entryname) or the catalog in which the entry 
being used as a model is defined (following 
catname). If you specify both passwords, the 
catalog's password is used. If protection 
attributes are not to be copied, any password can 
be used. 

catname 

specifies the name of the catalog in which the 
entry to be used as a model is defined. You 
identify the catalog that contains the model 
entry for either of these cases: 

• You specify the catalog's password instead of 
the model entry's password. 

• The model entry's catalog is not identified 
with a JOBCAT or STEPCAT DD statement, and is 
not the master catalog. 

OWNER(ownerid) 

specifies the identification of the owner of the page 
space. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character 
(that is, a comma [,], semicolon C;3, blank [b], 
period [.], single quote C'3, ampersand [&3, plus 
sign [+], equal sign C=3, hyphen C-3, parenthesis 
[( or )3, slash C/3, or asterisk t*3), enclose 
the ownerid in single-quotation marks (for 
example, 0WNER( '*D0RIS*' ) ) . 
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When the ownerid contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation 
marks (for example, 0WNER( '*CA " ROL* ' ) ) . 

You can code ownerid in hexadecimal form, where 
two hexadecimal characters represent one EBCDIC 
character. For example, 0WNER(X' E2E4C5 ' ) is the 
same as OWNER(SUE). 

Note to TSO users: If the owner is not identified 
with the OWNER parameter, the TSO user's userid 
becomes the ownerid. 

READPW C pa s swo rd ) 

specifies a read level password for the page space. 
Because the page space is a system data set, it cannot 
be opened or used by a user's program. 

The passwords are cataloged in both the v page space 
entry and its data component's entry. You should 
specify control-, update-, and read-level passwords to 
prevent the page space from being accessed if its 
volume is moved to a VS1 system. A VS2 system 
automatically prevents users from accessing page 
spaces and their data components. 

password 

is a 1 to 8 alphameric or special character 
password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character 
(that is, a comma C,3, semicolon [;3, blank Cb3, 
period [.], single quote C'3, ampersand [&], plus 
sign [+3, equal sign [=3, hyphen [-3, parenthesis 
[( or )3, slash C/3, or asterisk E*3), enclose 
the password in single-quotation marks (for 
example, READPW( ' *D0RIS* ' ) ) . 

When the password contains a special character 
and also contains a single-quotation mark, code 
the imbedded quotation mark as two 
single-quotation marks (for example, 
READPWCXCA' 'ROL*')). 

You can code password in hexadecimal form, where 
two hexadecimal characters represent one 
alphameric or special character. For example, 
READPW(X'E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

SMAPiNOSWAP 

specifies for which group of pages the page space will 
be used. Auxiliary Storage Management separates 
private-area address space pages into two distinct 
groups: Local System Queue Area (LSQA) pages and 
pageable private-area pages. SWAP specifies that the 
page space is a high-speed data set used during a swap 
operation to store and retrieve the set of LSQA pages 
owned by an address space. NOSWAP indicates that the 
page space is a conventional page space used to record 
pageable private area pages. 

A page space with the SWAP attribute cannot be defined 
on a 2314 direct access device. 

Abbreviation: NSWAP 
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TO(date)|FO!Udays) 

specifies the retention period for the page space. 

If neither TO nor FOR is specified, the page space can 
be deleted at any time. 

TO(date) 

specifies the date, in the form yyddd, where yy 
is the year and ddd is the number (001 through 
365) of the day, through which the cluster being 
defined is to be kept. 

FORtdays) 

specifies the number of days for which the page 
space is to be kept. The maximum number that can 
be specified is 9999. If the number specified is 
through 1830, the page space is retained for 
the number of days specified; if the number is 
between 1831 and 9999, the page space is retained 
through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal 
(X'n 1 ), or binary (B'n') form. 

UNIQUE I SUBALLOCATION 

specifies whether the page space is allocated an 
amount of space from the volume's available space 
(UNIQUE) or from a previously defined VSAM data space 
(SUBALLOCATION). When UNIQUE is specified, the page 
space is allocated a VSAM data space of its own. V5AM 
generates a name for the data space and builds a 
format-1 DSCB in the volume's VTOC to describe it. If 
SUBALLOCATION is specified, the name of the data 
space, not of the page space, appears in the VTOC. A 
data space must have been defined on the volume on 
which the page space is defined. 

Auxiliary Storage Management recommends that UNIQUE be 
used for page space data sets. This will cause VSAM to 
allocate a single nonshared data space for the page 
data set. Space from another data space will not be 
used, eliminating one of the possibilities for 
multiple extent data sets which will cause Auxiliary 
Storage Management performance degradation. 

Abbreviations: UNQ and SUBAL 

UPDATEPWC password) 

specifies an update-level password for the page space. 
Because the page space is a system data set, it cannot 
be opened or used by a user's program. 

If a read password is the only password specified for 
the page space (that is, it is the highest-level 
password), it propagates upward and becomes the 
password for all higher levels. If you specify a 
highei — level password and do not specify an update 
password, the update password is null. 

The passwords are cataloged in both the page space 
entry and its data component's entry. You should 
specify control-, update-, and read-level passwords to 
prevent the page space from being accessed if its 
volume is moved to a VS1 system. A VS2 system 
automatically prevents users from accessing page 
spaces and their data components. 

password 

is a 1 to 8 alphameric or special character 
password. 
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If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character 
(that.- is* a comma [J, semicolon [;3* blank Cb3, 
period C.3, single quote C f 3, ampersand C&3* plus 
sign [+3* equal sign [=3* hyphen [-3, parenthesis 
[(or )3, slash E/3, or asterisk C*3)> enclose 
the password in single-quotation marks (for 
example* UPDATEPWC f XDORIS* 1 >) . 

When the password contains a special character 
and also contains a single-quotation mark, code 
the imbedded quotation mark as two 
single-quotation marks (for example, 
UPDAT.EPUK'XCA'-'ROL**)..). 

You can code password in hexadecimal form* where 
two hexadecimal characters represent one 
alphameric or special character. For example* 
UPDATEPW(X'E2E4C5 f ) is the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 



Catalog (Page space) 



CATAL0G(catnameC/password3 ) 

specifies the name and password of the catalog in 
which the page space is to be defined. 

When the CATALOG parameter identifies a user catalog, 
you must also supply a STEPCAT or JOBCAT DD statement 
to describe and allocate the user catalog. See "Order 
of Catalog Use* DEFINE" fo»r information about the 
order in which catalogs are used. 

catname 

specifies the name of the catalog. 

password 

specifies a password. If the catalog is password 
protected, you must supply the catalog's update- 
or highei — level password. If no password is 
specified* VSAM asks the operator or TSO terminal 
user for the correct password. 

Abbreviation: CAT 
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DEFINE PAGESPACE EXAMPLES 

Define a conventional (NOSMAP) Page Space: Example 1 

In this example, a page space is defined. 

//DEFPGSP1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//VOLUME DD . VOL=SER=VSER05,UNIT=2305,DISP=OLD 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE PAGESPACE - 

(NAMECSYS1.PAGE2) - 

CYLINDERS(IO) - 

VOLUMESCVSER05) - 

CONTROLPW(PASSWDl) - 

UPDATEPWCPASSWD2) - 

READPWCPASSWD3)) 
/X 

The job control language statements are: 

• VOLUME DD, which describes the volume on which the data 
space is to be defined. 

• SYSPRINT DD, which is required in all Access Method 
Services job steps. The SYSPRINT DD statement 
identifies the output device to which Access Method 
Services messages to the programmer are to be sent. 

Because no catalog is explicitly specified with a CATALOG 
parameter or with JOBCAT or STEPCAT DD statements, VSAM 
assumes that the data space and page space are to be 
defined in the master catalog. 

The DEFINE PAGESPACE command defines a page space. This 
page space will have the UNIQUE attribute and hence a new 
data space will be created for its exclusive use. Its 
parameters are- 

• NAME, which specifies the name of the page space, 
SYS1.PAGE2. 

• CYLINDERS, which specifies that the page space is to 
occupy ten cylinders. The page spaces are never 
extended. 

• VOLUMES, which specifies that the page space is to 
reside on volume VSER05. 

• CONTROLPW, which specifies the control password for the 
page space is PASSWD1. 

• UPDATEPW, which specifies the update password for the 
page space is PASSWD2. 

• READPW, which specifies the read password for the page 
space is PASSWD3. 

Because neither UNIQUE nor SUBALLOCATION has been 
specified, the page space defaults to UNIQUE. Because 
neither SWAP nor NOSWAP has been specified, the page space 
defaults to NOSWAP. 

Define a SWAP Page Space: Example 2 

In this example, a unique page space is defined. A unique 
page space differs from a suballocated page space in that a 
unique page space occupies an entire VSAM data space. When 
a unique page space is defined, a VSAM data space is 
automatically built for the page space. When space is 
allocated to a unique page space, the volume's VTOC 
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identifies the space with the name of the page space. 

//DEFPGSP2 JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE PAGESPACE - 

(NAMECSYS1. PAGED - 

CYLINDERSC10) - 

VOLUMESCVSER05) - 

SWAP - 

C0NTR0LPWCPASSWD1) - 

UPDATEPWCPASSWD2) - 

READPWCPASSWD3)) 
/* 

The DEFINE PAGESPACE command defines a page space. Its 
parameters are* 

• NAME* which specifies the name for the page space: 
SYS1.PAGE1. Because the page space i s unique, the page 
space's name is put into the DSCB (in the volume's 
VTOC) that describes the space allocated to the page 
space. 

• CYLINDERS, which specifies that the page space occupies 
10 cylinders and cannot be extended. 

• VOLUMES, which identifies the volume on which the page 
space is to reside. Because no DD statement describes 
the volume, the volume i s dynami cally allocated. Volume 
VSER05 must be mounted as permanently resident or 
reserved. 

• SWAP, which specifies the page space will be used to 
store Local System Queue Area (LSQA) pages. 

• CONTROLPW, which specifies the control password for the 
page space is PASSWD1. 

• UPDATEPW, which specifies the update password for the 
page space is PASSWD2. 

• READPW, which specifies the read password for the page 
space is PASSWD3. 

Because neither UNIQUE nor SUBALLOCATION has been 
specified, the page space defaults to UNIQUE. 

Because neither a CATALOG parameter nor a JOBCAT or STEPCAT 
DD statement was specified, VSAM assumes that the page 
space is to be defined in the master catalog. 
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DEFINE PATH 



The format of the DEFINE command when it is used to define 
a path is* 



DEFINE 



PATH 

C NAME (en try name) 

PATHENTRYlentrynameC/password] ) 

CATTEMPTS(number|2)3 

[AUTHORIZATION(entrypoint[b string])] 

CCODE(code)] 

CCONTROLPU( password)] 

CFILE(dname)] 

CMASTERPUC password)] 

[MODEL (en try name [/password] 

[b catname[/password] ] )] 
[OWNER(ownerid)] 
[READPW( password)] 
[TO(date)|FOR(days)] 
[ UPDATE IN0UPDATE3 
[UPDATEPW(password)]) 

[CATALOG(catname[/password] )] 



DEFINE PATH Parameters: Summary 



The parameters of the DEFINE PATH command can be grouped as 
required and optional parameters. 

The required parameters are'- 

• Entry type, which specifies that a path catalog entry 
is to be created (PATH). 

• Name, which names the path and the entry that it points 
to (NAME and PATHENTRY). 

The optional parameters are : 

• Allocation, which identifies the catalog recovery 
volume that contains the alternate index or cluster 
that the path points to (FILE). This parameter is 
required when the path is defined in a recoverable 
catalog. 

• Protection and integrity, which 

identify the path to a console operator without 
revealing the path's entry name (CODE and 
ATTEMPTS). 

identify a user-wri tten-securi ty verification 
routine for additional authorisation verification 
(AUTHORIZATION). 

specify a retention period for the path (FOR or 
TO). 

associate passwords with the path (MASTERPW, 
CONTOLPW, UPDATEPW, and READPW). 

identify the owner of the path (OWNER). 

• Model, which identifies an existing path entry that is 
to be used as a model for the path being defined 
(MODEL). 

• Update, which specifies whether the cluster's upgrade 
set is to be opened when the path (and its cluster) is 
opened (UPDATE or NOUPDATE) . 
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• Catalog, which identifies the catalog that contains the 
alternate index or cluster entry that the path entry is 
to point to (CATALOG). 

DEFINE may be abbreviated: DEF. 
DEFINE PATH PARAMETERS 

Required Parameters 

PATH 

specifies that a path is to be defined. 

The PATH keyword is followed by parameters which name 
the path and its related object, and which specify the 
path's attributes. 

NAME (en try name) 

specifies the path's name. 

entryname 

can contain 1 to 44 alphameric characters (A 
through Z, and through 9), national characters 
(3> #, and $), and special characters (the hyphen 
(-), and the 12-0 overpunch (X'CO')). 

When the name contains more than eight 
characters, you divide the name into segments of 
1 to 8 characters each and separate the segments 
with (.) periods. The name's first character (and 
each segment* 5 first character) is either an 
alphabetic character or a national character. If 
you specify the path's name in the format 
entryname(modi f i er) , only that portion of the 
path's name preceding the left parenthesis will 
be used. The modifier enclosed in parentheses 
will be ignored. 

PATHENTRY(entrynameC/password] ) 

when the path consists of an alternate index and its 
base clusters, entryname identifies the 
alternate-index entry. When the path is opened to 
process data records, both the alternate index and the 
base cluster are opened. 

When the path consists of a cluster without an 
alternate index, entryname identifies the cluster. You 
can define the path as though it were an alias for the 
cluster. This allows you to specify no-update access 
to the cluster, so that the upgrade set will not be 
required or updated when the cluster is opened. You 
can also establish protection attributes for the 
alternate name, separate from the protection 
attributes of the cluster. 

If the cluster or alternate-index entry is password 
protected, you must supply the entry's master 
password. When you identify the catalog with the 
CATALOG parameter, you can supply the catalog's master 
password instead of the entry's password. 

Abbreviation: PENT 



Optional Parameters 



ATTEMPTS(number|2) 

specifies the maximum number of times the operator can 
try to enter a correct password in response to a 
prompting message. 
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This parameter can be coded, but only has effect when 
the path's master password is not null. A prompting 
message is issued only when the user has not already 
supplied the appropriate password. 

number 

is an integer from to 7 and can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

Note to TSO users: At a TSO terminal, the logon password 
is checked first before the user is prompted to supply a 
password for the path. Checking the logon password counts 
as one attempt to obtain a password. If ATTEMPTS is not 
specified, the user has one attempt to supply the path's 
password because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION(entrypointCb string]) 

specifies that a usei — security-verification routine (USVR) 
is available for additional security verification. When a 
protected path is accessed and the user supplies a correct 
password other than the cluster's master password, the USVR 
receives control. See OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide for details on the USVR. 

If a USVR is loaded from an unauthorized library during 
Access Method Services processing, an abnormal termination 
will occur. See the section "Authorized Program Facility" 
in the chapter "Introduction." 

This parameter can always be coded, but only has effect 
when the path's master password is not null. 

entrypoint 

specifies the name of the USVR. entrypoint can contain 
1 to 8 alphameric characters (A through Z, and 
through 9), national characters (3), #, and $), and 
special characters (the hyphen(-) and the 12-0 
overpunch (X'CO')). The name's first character is 
either an alphabetic character or a national 
character. 

string 

specifies information to be passed to the USVR when it 
receives control to verify authorization, string can 
contain 1 to 255 EBCDIC characters. 

When the string contains a special character (that is, 
a comma C , 3 , semi colon C ; 3 , blank [b] , peri od C . 3 , 
single quote C ' 3 , ampersand C&3, plus sign C+3, equal 
sign [=3, hyphen C-3, parenthesis [(or )], slash [/], 
or asterisk L*3), enclose the string in 
single-quotation marks (for example, AUTHORIZATION 
entrypoint, 'XDORIS*')). 

When the string contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two si nale-quotati on marks (for 
example, AUTHORIZATION entrypoint, ' *CA" ROL* ' ) ) . 

You can code string in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, AUTHORIZATION entrypoint, X'E2E4C5') is 
the same as AUTHORIZATION entrypoint, . SUE) .. The 
string can contain up to 255 hexadecimal characters 
when expressed in this form, resulting in up to 128 
bytes of information. 

Abbreviation: AUTH 
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CODEC code) 

specifies a code name for the path. If an attempt is made 
to access a password-protected path without first supplying 
an appropriate password, a prompting message i s issued to 
the operator's console. The prompting message includes the 
code name, which identifies the path without revealing its 
entry name. 

This parameter can be coded, but only has effect when the 
path's master password is not null. A prompting message is 
issued only when the user hasn't already supplied the 
appropriate password. When CODE is not specified, the 
prompting message identifies the path with its entry name. 



code 



can contain 1 to 8 alphameric or special characters. 



When the code contains a special character (that is, a 
comma [,], semicolon [;3, blank Cb], period [.], 
single quote C'3, ampersand [&3, plus s^ gn [+3, equal 
sign [=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the code in single-quotation 
marks (for example, C0DE( * XDORIS* ' ) ) • 

If the code contains a lowercase alphabetic character 
it is folded to an uppercase alphabetic character. 

When the code contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, C0DE( ' *CA"R0LX' ) ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0DE(X' E2E4C5 T ) is the 
same as CODE(SUE) . 




pa sswo 

base cluster. 

If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 



password 

is a 1 to 8 alphameric or special character password, 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 



When the password contains a special character (that 
is, a comma t,3, semicolon C;3, blank Cb3, period C.3, 
single quote C'3, ampersand C&J, plus sign C+3, equal 
sign [=3, hyphen C-3, parenthesis [( or )3, slash [/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
CONTROLPWCXDORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, C0NTR0LPW( ' *CA" ROL*' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, C0NTR0LPW(X' E2E4C5* ) 
is the same as CONTROLPW(SUE) . 
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Abbreviation: CTLPW 



FILE(dname) 

specifies the name of a DD statement that identifies the 
recovery volume of the alternate index or cluster named 
with the PATHENTRY parameter. FILE is only required when 
the path is defined in a recoverable catalog. 

The recovery volume is the first volume of the base 
cluster's index component when PATHENTRY names a 
key-sequenced cluster or an alternate index over a 
key-sequenced cluster. 

The recovery volume is the first volume of the base 
cluster's data component when PATHENTRY names an 
entry-sequenced cluster or an alternate index over an 
entry-sequenced cluster. 

When FILE is not specified, the cluster's recovery volume 
is dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

MASTERPU(password) 

specifies a master password for the path. The master 
password allows all operations against the path. 

If the master password is not specified* the path's 
highest-level password propagates upward and becomes the 
password for all higher levels* including the master 
password. 

If all passwords &r& null, ATTEMPTS, AUTHORIZATION, and 
CODE can be coded but have no effect until the master 
password is specified. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [>3, semicolon C;3, blank Cb3, period [.], 
single quote ['3, ampersand [&3, plus sign C+3, equal 
sign C=3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk [*3), enclose the password in 
single-quotation marks (for example, 
MASTERPW('*DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, MASTERPW( ' *CA "ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, MASTERPW(X' E2E4C5 ' ) is 
the same as MASTERPW(SUE) . 

Abbreviation: MRPW 

MODEL ( en try name C /password 3 

Cb catnameC/password3 3 ) 

identifies an existing path entry that is to be used as a 
model for the path being defined. For details about how a 
model is used, see "How to Use One Object as a Model for 
Another Object." 

You can use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the path. When you do not want to add or change any 
attributes, you specify only the entry-type (PATH), the 
path's name, its alternate-index's (or cluster's) name, and 
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the model-entry's name. 

entryname 

names the entry to be used as a model, entryname must 
name a path entry. 

password 

specifies a password. If the model entry is password 
protected and it is cataloged in a password-protected 
catalog* you must supply the read (or higher level) 
password of either the model entry or its catalog. If 
you specify both passwords* the catalog's password is 
used. 

If you are not specifying new protection attributes 
for the path (that is* the model's passwords and 
protection attributes are being copied)* you must 
supply the master password of either the model entry 
or its catalog. 

catname 

names the model-entry's catalog. You must identify the 
catalog that contains the model entry for either of 
these cases 1 

• You specify the catalog's password instead of the 
model-entry's password 

• The model-entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement* and is not the 
master catalog. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. See "Order of 
Catalog Use** DEFINE" for information about the order 
in which a catalog is selected when the catalog's name 
i s not speci f i ed. 

OWNER ( owner id) 

specifies the identification of the path's owner. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character (that 
is, a comma C , 3 , semicolon C;3, blank [b3* period [.3* 
single quote C'3, ampersand ill, plus sign C+3* equal 
sign C=3* hyphen C-3, parenthesis {( or )3, slash £/3* 
or asterisk E*3), enclose the ownerid in 
single-quotation marks (for example, 
OWNER('KDQRISX')). 

When the ownerid contains a special character and also 
contains a single-quotation mark* code the imbedded 
quotation mark as two single-quotation marks (for 
example, 0WNER( '*CA" ROL* ' ) ) . 

You can code ownerid in hexadecimal form* where two 
hexadecimal characters represent one EBCDIC character. 
For example, 0WNER(X' E2E4C5' ) is the same as 
OWNER(SUE). 

Note to TSO users: If the owner is not identified with the 
OWNER parameter* the TSO user's userid becomes the ownerid. 

READPUC password) 

specifies a read password for the path. The read password 
permits read operations against the base cluster's data 
records. 

password 

is a 1 to 8 alphameric or special character password. 
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If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,3, semicolon [;3, blank Lb3, period [.3, 
single quote ['3, ampersand C&3, plus sign [ + 3, equal 
sign [ = 3, hyphen [-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
READPW('*DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, READPW( ' *CA " ROL*' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, READPW(X' E2E4C5 ' ) is 
the same as READPW(SUE). 

Abbreviation: RDPW 

TO(date)|FOR(days) 

specifies the retention period for the path. The path is 
not automatically deleted when the expiration date is 
reached. When a retention period is not specified, the path 
can be deleted at any time. 

TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the path 
is to be kept before it is allowed to be deleted. 

FOR (days) 

specifies the number of days for which the entry is to 
be kept before it is allowed to be deleted, days can 
be expressed in decimal (n), hexadecimal (X'n'), or 
binary (B'n') form. The maximum number that can be 
specified for days is 9999. If the number specified is 
through 1830, the retention period is the number of 
days specified. If the number specified is between 
1831 and 9999, the retention period is through the 
year 1999. 

UPDATE 1NOUPDATE 

specifies whether the base-cluster's upgrade set is to be 
allocated when the path is opened for processing. 

The upgrade set is a group of alternate indexes associated 
with the base cluster. The alternate indexes are opened 
whenever the base cluster is opened. When records in the 
base cluster are modified or deleted, and when records are 
added to the base cluster, each alternate index in the 
base-cluster's upgrade set is modified to reflect the 
change in the cluster's data, just as a key-sequenced 
cluster's index is modified each time the cluster's data 
changes. 

When a path points to a base cluster that has a large 
upgrade set (that is, many alternate indexes are associated 
with the base cluster), and the path, is defined with the 
NOUPDATE attribute, you can open the path, and consequently 
the base cluster, and none of the alternate indexes will be 
opened. 

NOUPDATE specifies that, when opening the path, the path's 
base cluster is to be allocated and the base cluster's 
upgrade set is not to be allocated. You can specify the 
NOUPDATE attribute for the path even though the UPGRADE 
attribute is set for one of the base-cluster's alternate 
indexes. 
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Abbreviations: UPD and NUPD 

UPDATEPU(password) 

specifics the update password for the path. The update 
password permits read and write operations against the base 
cluster's data records. 

If a read password is the only password specified for the 
object (that is, it is the highest-level password)* it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei — level password and don't 
specify an update password, the update password is null. 

password 

i s a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma [,3, semicolon C;3, blank Eb3, period C.3, 
single quote C'3> ampersand C&3, plus sign [+3, equal 
sign [=]> hyphen [-3, parenthesis C( or )3, slash [/3, 
or asterisk t*3), enclose the password in 
single-quotation marks (for example, 
UPDATEPWCXDORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, UPDATEPW( ' *CA" ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, UPDATEPW(X' E2E4C5 ' ) is 
the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 



Catalog (Path) 



The catalog parameter allows you to supply the name and password 
of the catalog in which the path is to be defined. 

CATAL0G(catname[/password3 ) 

identifies the catalog that contains the entry of the 
cluster or alternate index named in the PATHENTRY 
parameter. 

See "Order of Catalog Use* DEFINE" for information about 
the order in which a catalog is selected if the catalog's 
name is not specified. 

If the cluster's or alternate-index's entry is password 
protected and its catalog is also password protected, you 
must specify the master password for either the entry or 
the catalog. 

catname 

specifies the catalog's name. 

password 

specifies the catalog's master password. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 
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DEFINE PATH EXAMPLE 



Define a Path: Example 1 



In this example, a path is defined. Previous examples 
illustrated the definition of the path's alternate index, 
EXAMPLE. AIX, and the alternate index's base cluster, 
EXAMPLE. KSDS2. The alternate index, path, and base cluster an 
defined in the same catalog, AMASTCAT. 

//DEFPATH JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 
DEFINE PATH - 

(NAME(EXAMPLE.PATH) - 
PATHENTRYCEXAMPLE.AIX/AIXMRPW) - 
READPW(PATHRDPW) ) - 
CATALOGCAMASTCAT/MCATUPPW) 

/* 



The job control language statement is : 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE PATH command builds a path entry to define the path 
EXAMPLE. PATH . A copy of the path entry is placed in the catalog 
ecovery area, since the path entry is being defined into a 
ecoverable catalog. The catalog recovery area on volume VSER04 
s dynamically allocated. The command's parameters are : 

NAME, which specifies that the path's name is EXAMPLE. PATH . 

PATHENTRY, which identifies the alternate index, 
EXAMPLE. AIX, that the path provides access to. 

READPW, which specifies the path's read password, PATHRDPW. 

CATALOG, which in this example supplies the master catalog's 
update password, MCATUPPW. 
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DEFINE SPACE 



The format of the DEFINE command when it is used to define a 
data space i s- 



DEFINE 



SPACE 

({CANDIDATE I 

CYLINDERSCprimaryCb secondary] ) | 
RECORDSCprimaryCb secondary]) 

b RECORDSIZECaverage b maximum) 
TRACKS(pri maryCb secondary])} 
VOLUMESCvolserCb volser...]) 
CFILECdname)]) 

CCATALOGCcatnameC/password] )] 



The parameters of the DEFINE SPACE command can be divided into 
required and optional parameters. 

The required parameters are : 

• Allocation, which specifies the amount and type of space to 
be allocated to the data space, and the volume that is to 
contain the data space (VOLUMES, CYLINDERS, RECORDS, TRACKS, 
RECORDSIZE, and CANDIDATE). 

The optional parameters are'' 

• Allocation, which 5 

Specifies the DD statement which identifies and 
allocates the volume where the space is to be allocated 
(FILE). 

• Catalog, which identifies the catalog in which the data 
space is to be defined (CATALOG). 

DEFINE may be abbreviated*- DEF. 



DEFINE SPACE PARAMETERS 



Required Parameters 
SPACE 



specifies that a data space is to be defined. You can also 
use the DEFINE SPACE command to reserve a volume for VSAM*s 
future use. The SPACE keyword is followed by the allocation 
parameters, enclosed in parentheses, that describe the 
space, and by the catalog parameter that identifies the 
catalog that owns the volume. 

Abbreviation: SPC 

CANDIDATE I 

CYLINDERS(primary[b secondary])! 

RECORDSCprimaryCb secondary] )b RECORDSIZECaverage b maximum) I 

TRACKS(primaryCb secondary)) 

specifies a volume(s) is to be reserved for VSAM's future 
use or specifies the amount of space to be allocated in 
terms of cylinders, number of records, or tracks. 

CANDIDATE 

specifies that the volumes listed in the VOLUMES parameter 
are reserved for future use by VSAM. An ownership indicator 
is set in a format-4 DSCB in the volume's table of contents 
(VTOC). The volumes are reserved for use by the catalog, 
but no space is allocated (other than the primary CRA 
allocation if the catalog is recoverable). Each volume so 
reserved is called a candidate volume. If CANDIDATE is not 
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specified, you must specify one of the following 
parameters: CYLINDERS, TRACKS, or RECORDS. 

If a VSAM data space already exists on the volume, you 

cannot specify CANDIDATE. (You can, however, use the ALTER 

command to identify the volume as a candidate volume for a 

VSAM object other than the volume's catalog.) 

Abbreviation: CAN 

CYLINDERS(primary[b secondary] ) | 

RECORDSCprimaryCb secondary]) 

b RECORDSIZEtaverage b maximum)! 

TRACKS(primaryCb secondary]) 

specifies the amount of space to be allocated in terms of 
tracks, cylinders, or number of records. If RECORDS is 
specified, the space required is calculated in terms of the 
number of records, but the space is allocated by tracks. 
However, if you specify TRACKS or RECORDS and if the 
minimum number of tracks should exceed a cylinder, space is 
allocated in terms of cylinders. 

primary 

specifies the initial amount of space (primary extent) 
to be allocated to the data space, primary can be 
expressed in decimal (n), hexadecimal (X'n'), or 
binary (B'n') form. 

secondary 

specifies the amount of space that is to be allocated 
to the data space each time it is extended. Once the 
primary extent is filled, the data space can expand to 
include a maximum of 15 secondary extents if you have 
specified a secondary-extent amount, secondary can be 
expressed in decimal (n), hexadecimal (X'n'), or 
binary (B'n') form. 

The secondary space allocation is rounded upward to 
the nearest whole cylinder regardless of your 
specification in terms of TRACKS or RECORDS. 
Consequently, the total amount of space allocated to 
the data space might exceed the predicted limit. 

When the data space is the first data space on a volume 
that belongs to a recoverable catalog, the primary amount 
is increased by one cylinder. 

You must specify one, and only one, of the following 
parameters'- CANDIDATE, CYLINDERS, TRACKS, or RECORDS. When 
you specify RECORDS, you must also specify RECORDSIZE. When 
you specify CYLINDERS or TRACKS, you cannot specify 
RECORDSIZE. 

Abbreviations: CYL, REC, and TRK 

RECORDSIZEtaverage b maximum) 

specifies the average and maximum lengths, in bytes, 
of the records. 

average and maximum can be any integer value between 1 
and 32,761, expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. When you specify the 
RECORDS parameter, you must also specify RECORDSIZE. 
Otherwise, you cannot specify RECORDSIZE. 

Abbreviation: RECSZ 

VOLUMEStvolserCb volser...]) 

specifies the volumes on which data spaces are to be 
defined. If two or more volumes are specified and an amount 
of space is specified (that is, TRACKS, CYLINDERS, or 
RECORDS and RECORDSIZE is specified) the amount specified 
for the primary allocation is allocated on each volume. The 
specified volumes must all be of the same device type. When 
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the volume already has a data space on it, subsequent data 
spaces can be defined and must be cataloged in the catalog 
that owns the volume. A data space can be defined on a mass 
storage volume. 

A volume serial number, volser, may contain 1 to 6 
alphameric, national (3, #, and $), and, except under TSO, 
special characters. The special characters include commas, 
blanks, semicolons, parentheses, slashes, asterisks, 
periods, quotation marks, ampersands, plus signs, hyphens, 
and equal signs. A volume serial number must be enclosed in 
single quotation marks if it contains a special character. 
Single quotation marks within a volume serial number must 
be coded as two single quotation marks. 

Abbreviation: VOL 



Optional Parameters 



FILE(dname) 

specifies the name of the DD statement that identifies the 
device type and volumes to be used for space allocation. 
You cannot use concatenated DD statements to describe more 
than one volume. 

If FILE is not specified and the volume is physically 
mounted, the volume(s) identified with the VOLUMES 
parameter is dynamically allocated. Each dynamically 
allocated volume must be mounted as permanently resident or 
reserved. 



Catalog (Space) 



CATALOGtcatnamet/password] ) 

identifies the catalog in which the data space is to be 
defined. The catalog parameter is used to supply the name 
and password, when required, of the catalog that contains 
the volume entry that describes the volume on which the 
data space is to be allocated. If the DEFINE SPACE command 
is used to allocate the volume's first VSAM data space or 
to identify the volume as a candidate volume, the catalog 
parameter identifies the catalog that is to contain the 
volume's catalog entry and is to own the volume. (For more 
information about VSAM volume ownership, see the section 
"VSAM Volume Ownership" in the "Introduction.") 

If the catalog's volume is physically mounted, it is 
dynamically allocated. See "Order of Catalog Use: DEFINE" 
for information about the order in which catalogs are used. 

catname 

specifies the name of the catalog. 

password 

specifies a password. If the catalog is password 
protected, you must supply the update- or highei — level 
password. 

Abbreviation: CAT 
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DEFINE SPACE EXAMPLE 

. Define a Data Space: Example 1 

In this example* a data space is defined. The data space is to 
be used to allocate space for VSAM clusters that are 
subsequently defined. 

//DEFSPC1 JOB .... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
DEFINE SPACE - 

(CYLINDERSC100 10) - 
VOLUMES(VSER05)) 
/x 

VSAM assigns a name to the data space and keeps track of it for 
future data set space allocation. Because no user catalog is 
specified in this example, the master catalog is assumed as the 
default. (It is the first catalog found because no JOBCAT or 
STEPCAT DD statements were specified. See the previous section 
"Order of Catalog Use: DEFINE" for more details.) 

The job control language statement is : 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE SPACE command defines a VSAM data space. Its 
parameters are: 

• CYLINDERS, which specifies that 100 cylinders are to be 
allocated for the data space. When the data space is 
extended, it is to be extended in increments of ten 

cyl i nders. 

• VOLUMES, which specifies the volume serial number of the 
volume on which the data space is to be defined 1 VSER05. 

Access Method Services defines the data space and allocates its 
space on volume VSER05. The data space is cataloged in the 
master catalog, because the DEFINE command does not include a 
CATALOG parameter, and because no JOBCAT or STEPCAT DD 
statements are specified. All future data spaces and clusters on 
volume VSER05 must also be cataloged in the master catalog. 
NonVSAM data sets on the volume reside in areas that are not 
allocated to a VSAM data space. 

To reserve a 3330 volume for VSAM's exclusive use, define the 
data space on it as 403 cylinders (this allows one cylinder to 
be used for the volume's table of contents — VTOC — and the 
volume's label) or define other data spaces on the volume with 
additional DEFINE SPACE commands (which can be given in the same 
job step) so that all the volume's space is part of a VSAM data 
space. 
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When you define a catalog, you can specify attributes for the 
catalog as a whole and for the catalog's components. 

The format of the DEFINE command when it is used to define a 
catalog i s : 



DEFINE 



USERCATALOG | MASTERCATALOG 

( NAME ( en t ryname ) 

{CYLINDERS(primaryLb secondary] ) | 
RECORDSCpri maryCb secondary] )| 
TRACKStpri maryLb secondary])} 

VOLUME(volser) 

[ATTEMPTS(numberl2)] 

CAUTHORIZATION(entrypoint[b string])] 

[BUFFERSPACEC si ze I 3072 ) 3 

CCODE(code)] 

[CONTROLPWt password)] 

[DESTAGEWAIT i NODESTAGEWAIT ] 

CFILECdname)] 

CHASTERPU( password)] 

C MODEL ( en t ryname [/password] 
[b catnameC/password] ] ) ] 

[OWNER(ownerid)] 

[READPW( password)] 

[RECOVERABLE 1 NOTRECOVERABLE ] 

[TO(date)|FOR(days)] 

[UPDATEPW( password)] 

[WRITECHECK 1 NOWRITECHECK ] ) 

[DATA 

UBUFFERSPACE(size)] 
[CYLINDERSCprimarylb secondary] ) I 

RECORDS(primary[b secondary])! 

TRACKS(primary[b secondary])] 
[DESTAGEWAIT | NODESTAGEWAIT ] 
[RECOVERABLE | NOTRECOVERABLE] 
[WRITECHECK | NOWRITECHECK] ) ] 

[INDEX 

([CYLINDERS(primary)| 

RECORDS(primary) I 

TRACKS(primary)] 
[DESTAGEWAIT | NODESTAGEWAIT] 
[WRITECHECK I NOWRITECHECK] )] 

[CATALOG (master cat name [/password) )] 



DEFINE USERCATALOG Parameters: Summary 



The parameters of the DEFINE USERCATALOGlMASTERCATALOG command 
can be divided into required and optional parameters. 

The required parameters are : 

• Entry type, which specifies that a user catalog is to be 
defined (USERCATALOG or MASTERCATALOG). 

• Name, which names the catalog (NAME). 

• Allocation, which 

Specifies the space to be allocated for the catalog's 
data space (one of CYLINDERS, RECORDS, or TRACKS). 

Specifies the volume on which the catalog is to reside 
(VOLUME). 
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The optional parameters are : 

• Allocation, which describes? 

The name of the DD statement which describes the catalog 
volume (FILE) . 

The space for the catalog itself (one of CYLINDERS, 
RECORDS, or TRACKS). 

The space to be used for buffers when the catalog is 
accessed (BUFFERSPACE) . 

Whether a catalog recovery area is to be defined 
(RECOVERABLE or NOTRECOVERABLE) . 

• Protection and integrity, which 

Associate passwords with the catalog. (MASTERPW, 
CONTROLPW, UPDATEPW, READPW) . 

Provide a mechanism by which the console operator can be 
prompted to supply a password without disclosing the 
name of the catalog (CODE). 

Identify a usei — written routine for additional 
authorization verification (AUTHORIZATION). 

Identify the owner of the catalog (OWNER). 

Specify the time for which the cataiog is to be kept (TO 
or FOR). 

Specify whether the write-check operation is to be 
performed (WRITECHECK or NOWRITECHECK) . 

Specify whether a user catalog that is stored on a mass 
storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes 
it (DESTAGEWAIT or NODESTAGEWAIT) . 

• Model, which identifies an existing catalog from which 
attributes are to be copied for the definition of a new user 
catalog (MODEL). 

• Components, which allows you to specify attributes 
separately for the catalog's data and index components (DATA 
and INDEX). 

• Catalog, which supplies the name and password, when 
required, of the master catalog (CATALOG). 

DEFINE can be abbreviated: DEF. 
DEFINE USERCATALOG PARAMETERS 

Required Parameters 

USERCATALOG(options) 

specifies that a user catalog is to be defined. USERCATALOG 
is followed by the parameters specified for the catalog as 
a whole. 

(In 0S/VS2 MVS, when you specify MASTERCATALOG the result 
is the same; a user catalog is created. You can, however, 
establish a user catalog as a master catalog at IPL time. 
See "Appendix H: Changing the Attributes of the VSAM Master 
Catalog" for a description of this procedure.) 

Abbreviation: UCAT 
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NAME (en try name) 

specifies the name of the catalog being defined. 

The name may contain from 1 through 44 alphameric 
characters (A through Z, and through 9), national 
characters (3), #,. and $), and two special characters (the 
hyphen and the 12-0 overpunch) . 

Names containing more than eight characters must be 
segmented by periods; one to eight characters may be 
specified between periods. The first character of any name 
or name segment must be either an alphabetic or a national 
character. If you specify the name in the format entryname 
(modifier), only that portion of the name preceding the 
left parenthesis will be used. The modifier enclosed in 
parentheses will be ignored. 

CYLINDERSCprimaryCb secondary] )| 

RECORDStprimaryCb secondary] )| 

TRACKSfprimaryCb secondary]) 

specifies the amount of space to be allocated in terms of 
tracks, cylinders, or number of records. You can specify 
the amount of space as a parameter of USERCATALOG, as a 
parameter of USERCATALOG and DATA, or as a parameter of 
USERCATALOG, DATA, and INDEX. See the section "How Space is 
Assigned to a Catalog" for a description of the difference 
in space allocation depending on which combination you use. 
See the section "Estimating the Catalog's Space 
Requirements" for information about estimating the amount 
of space to be specified for a catalog. 

When you specify less than one cylinder of space, and the 
catalog is defined as recoverable (see the RECOVERABLE 
parameter), your DEFINE command will fail. 

primaryCb secondary] 

specify the size of the primary and secondary extents 
to be allocated. Once the primary extent is filled, 
the space can expand to include a maximum of 13 
additional secondary extents if you have specified a 
secondary allocation amount. 

primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n 1 ) form. Secondary 
allocation should be specified in case the catalog has to 
be extended. 

Abbreviations: CYL, REC, and TRK 

VOLUME(volser) 

specifies the volume that is to contain the catalog. The 

volume cannot be currently owned by any other VSAM catalog. 

A user catalog can be defined on a mass storage volume. 

A volume serial number, volser, may contain 1 to 6 
alphameric, national (3, #, and $), and special characters; 
the special characters include commas, blanks, semicolons, 
parentheses, slashes, asterisks, periods, quotation marks, 
ampersands, plus signs, hyphens, and equal signs. A volume 
serial number must be enclosed in single quotation marks if 
it contains a special character. Single quotation marks 
within a volume serial number must be coded as two single 
quotation marks. 

The VOLUME parameter interacts with other DEFINE CATALOG 
parameters. You should take care to ensure that the volume 
you specify for the catalog can satisfy the catalog's other 
attributes* 

• CYLINDERS, RECORDS, TRACKS- The volume contains enough 
unallocated space to satisfy the catalog's primary 
space requirement. (Space on the volume might already 
be allocated to nonVSAM data sets and system data sets. 
However, the volume cannot be owned by another VSAM 
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catalog — that is, no space on the volume can already be 
allocated to VSAM objects.) 

• FILE** The volume information supplied with the DD 

statement is consistent with the information specified 
for the catalog and its components. 

Abbreviation: VOL 



Optional Parameters 



ATTEMPTS(number|2) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

number 

is an integer from to 7 and can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. If is specified, the operator is not prompted 
and is not allowed to enter a password from the 
console. 

Note to TSO Users: At a*TS0 Terminal the logon password is 
checked first before the user is prompted to supply a 
password for the catalog. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the 
catalog's password, because the default is 2. 

Abbreviation: ATT 

AUTHORIZATIONtentrypointCb string] ) 

specifies that a usei — security-verification routine (USVR) 
is available for additional security verification. When a 
protected catalog is accessed and the user supplies a 
correct password other than the catalog's master password, 
the USVR receives control. See "Usei — Written Exit Routines" 
in OS/VS Virtual Storage Access Method (VSAM) Programmer's 
Gui de for information on the user-security-verification 
routine. 

entrypoint 

specifies the name of the USVR. entrypoint can contain 
1 to S alphameric characters (A through Z, and 
through 9), or national characters (2, #, $), and 
special characters (the hyphen (-) and the 12-0 
overpunch (X'CO')). The name's first character is 
either an alphabetic character or a national 
character. 

string 

specifies information to be passed on to the USVR when 
it receives control to verify authorization, string 
can contain 1 to 255 EBCDIC characters. 

When the string contains a special character (that is, 
a comma C,3, semicolon C;3, blank Cb3, period [.], 
single quote ['3, ampersand C&3, plus sign C+3, equal 
sign [=3, hyphen C-3, parenthesis C( or )3, slash C/3, 
or asterisk [*]), enclose the string in 
single-quotation marks (for example, 
AUTHORIZATION(entrypoint, 'XDORIS*' )) . 

When the string contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, AUTHORIZATION entrypoi nt , ' *CA " ROL* ' ) ) . 

You can code string in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, AUTHORIZATION(entrypoi nt , X'E2E4C5') is 
the same as AUTHORIZATION(entrypoi nt, SUE). The string 
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can contain up to 255 hexadecimal characters when 
expressed in this form, resulting in up to 128 bytes 
of information. 

Abbreviation: AUTH 

BUFFERSFACEt si ze 1 3072 ) 

specifies the minimum space, in bytes, to be provided for 
buffers when using the catalog. Decimal values you can 
specify are 3072, 4096, 5120, 6144, 7168, and 8192. 

si ze 

is the amount of space, in bytes, to be provided for 
buffers, size can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B T n f ) form. 

Abbreviation: BUFSP 

CODE(code) 

specifies a code name for the catalog being defined. If an 
attempt i s made to access a password-protected catalog 
without a password, the code name is used in a prompting 
message; the code enables the operator to be prompted for 
the password without disclosing the name of the catalog. If 
CODE is not specified, the operator is prompted with the 
name of the catalog. 

code 

can contain 1 to 8 alphameric or special characters. 
When the code contains a special character (that is, a 
comma [,], semicolon [;], blank Cb3, period [.], 
single quote C'3, ampersand [&], plus sign [ + 3, equal 
sign [=], hyphen C-3, parenthesis C( or )3, slash [/3, 
or asterisk E*3), enclose the code in single-quotation 
marks (for example, C0DE( ' *D0RIS* ' ) ) . 

If the code contains a lowercase alphabetic character 
it will be folded to an uppercase alphabetic 
character. 

When the code contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, C0DE( » *CA ' ' ROL*') ) . 

You can code code in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, CODE (X'E2E4C5') is 
the same as CODE(SUE). 

CONTROLPW(password) 

specifies a control password for the catalog being defined. 
The control password permits the same operations as the 
update password. 

If a read or update password is the only password specified 
for the catalog, it (the highest-level password) propagates 
upward and becomes the password for all higher levels. When 
the master password is specified but the control password 
is not specified, the control password is null. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb3, period C.3, 
single quote [ T 3, ampersand [&3, plus sign [+3, equal 
sign C=3, hyphen C-3, parenthesis C( or )3, slash [/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
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CONTROLPW( T *DORIS* f )). 



When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, CONTROLPWC ' *CA "ROL* ? ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, CONTROLPkKX' E2E4C5 ' ) 
is the same as CONTROLPW(SUE) . 

Abbreviation: CTLPW 

DESTAGEUAIT 1 NODESTAGEUAIT 

specifies whether a user catalog that is stored on a mass 
storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 

DESTAGEWAIT 

indicates that destaging is to be completed before 
control is returned from VSAM to the program that 
issues the CLOSE macro. VSAM can thus notify the 
program whether destaging was successful. 

Abbreviation: DSTGW 

NODESTAGEUAIT 

indicates that notification of unsuccessful destaging 
i s to be made only by a message to the operator. 

Abbreviation: NDSTGW 

If the user catalog is not stored on a mass storage volume, 
the attribute is ineffective until the di rect access 
storage volume the catalog is stored on is converted to a 
mass storage volume (by way of the CONVERTV command, which 
is described in OS/VS Mass Storage System (MSS) Services: 
Reference Information ) . 

If one of these parameters is specified for the data 
component of a catalog and the other parameter is specified 
for the index component, the parameter specified for the 
index component applies to both components, because the 
sequence set of the index of a catalog is imbedded in the 
data. 

FILE(dname) 

specifies the name of the DD statement that identifies the 
device and volume to be used for the catalog. The DD 
statement should specify DISP=0LD to prevent premature 
space allocation on the volume. If FILE is not specified 
and the catalog's volume is physically mounted, the volume 
identified with the VOLUME parameter is dynamically 
allocated. The volume must be mounted as permanently 
resident or reserved. 

MASTERPWC password) 

specifies a master password for the catalog being defined. 
A catalog must be master password protected in order to 
password protect any VSAM data sets cataloged in it. The 
AUTHORIZATION, CODE, and ATTEMPTS parameters have no effect 
unless the catalog has a master password associated with 
it. The master password allows all operations; it is 
required to open the catalog as a data set. 

If a master password is not specified for the catalog, the 
catalog's highest-level password propagates upward and 
becomes the password for all higher levels, including the 
master password. The master password is null when no other 
passwords are specified. 



Command Format 259 



password 

is a 1 to- 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
isr a comma C , 3 , semicolon E;3, blank Cb3, period C.3, 
single quote C ' 3 , ampersand I&3, plus sign [ + 3, equal 
sign 1 = 3, hyphen [-3, parenthesis E( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
MASTERPW('*DORIS* f )). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, MASTERPW( '*CA ' ' ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, MASTERPW(X f E2E4C5 ' ) is 
the same as MASTERPW(SUE) . 

Abbreviation; mrpw 

M0DEL(entrynamet/password3 [b catname[/password3 3 ) 

specifies that an existing master or user catalog is to be 
used as a model for the user catalog being defined. For 
details about how a model is used, see "How to Use One 
Object as a Model for Another Object." 

It is possible to use an already defined master or user 
catalog as a model for another user catalog. When one entry 
is used as a model for another, its attributes are copied 
as the new entry is defined. You may use some attributes of 
the model and override others by explicitly specifying them 
in the definition of the user catalog. 

If a model is used, you must specify certain parameters 
even though no attributes are to be changed or added. The 
name of the user catalog to be defined and volume and space 
information always must be specified as parameters of 
USERCATALOG. 

entryname 

specifies the name of the master or user catalog to be 
used as a model. 

password 

specifies a password. If the catalog to be used as a 
model is password protected, a password is required. 
If you specify both passwords (that is, the password 
following entryname and the password following 
catname), the password following catname is used for 
authorisation. If the protection attributes are to be 
copied, enter the master password of the catalog being 
used as a model. If passwords are not to be copied, 
any password except the master can be used. 

catname 

specifies the name of the catalog to be used as a 
model. This parameter is required if the model catalog 
is neither the master catalog nor a catalog identified 
by a JOBCAT or STEPCAT DD statement. 

OWNER (owner id) 

specifies the identification of the owner of the catalog 
being defined. 

ownerid 

can contain 1 to 8 EBCDIC characters. 
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When the ownerid contains a special character (that 
is, a comma [,3, semicolon C;3, blank Cb3, period C.3, 
single quote ['3, ampersand ill, plus sign [ + 3, equal 
sign [ = 3, hyphen [-3, parenthesis C( or )3, slash [/3, 
or asterisk C*3), enclose the ownerid in 
single-quotation marks (for example, 
0WNER('*D0RIS*')). 

When the ownerid contains a special character and also 
contains a single-quotation mark, code the imbedded 
quotation mark as two single-quotation marks (for 
example, 0WNER( ' *CA"R0L*» ) ) . 

You can code ownerid in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, 0WNER(X' E2E4C5 ' ) is the same as 
OWNER(SUE). 

READPWC password) 

specifies a read password for the catalog being defined. 
The read password permits the user to list the catalog's 
entries (passwords and protection attributes ar^ listed 
only when the master-level password is supplied). 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb3, period C.3, 
single quote ['3, ampersand C&3, plus sign C+3, equal 
sign C=3, hyphen C-3, parenthesis [( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
READPW('*DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
(for example, READPW( ' CA ' ' ROl* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, READPW(X' E2E4C5' ) is 
the same as READPW(SUE). 

Abbreviation: RDPW 

RECOVERABLE | NOTRECOVERABLE 

specifies that a catalog recovery space is to be created on 
each volume owned by the catalog. 

On the catalog's volume, the catalog recovery space is 
allocated from the catalog's data space. On subsequent 
volumes owned by the catalog, the catalog recovery space is 
allocated from the first data space defined on the volume. 
Primary allocation for a CRA is one cylinder. Once a 
primary extent is filled, the CRA can expand to include a 
maximum of 15 additional extents. Allocation for each 
secondary extent is one cylinder. The number of records a 
CRA can contain varies with the device type (for example, 
for a 3330 with 20 control intervals per track, each extent 
will accommodate approximately 370 records). 

Abbreviations: RVBL and NRVBL 

TO(date)|FOR(days) 

specifies the retention period for the catalog being 
defined. If no value is coded, the catalog can be deleted 
whenever it is empty. 
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TO(date) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day, through which the catalog being defined is to be 
kept. 

FOR(days) 

specifies the number of days for which the catalog 
being defined is to be kept. The maximum number that 
can be specified is 9999. If the number specified is 
through 1830, the catalog is retained for the number 
of days specified; if the number is between 1831 and 
9999, the catalog is retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal 
(X'h'), or binary (B'n') form. 

UPDATEPW(password) 

specifies an update password for the catalog being defined. 
The update password permits entries to be added to the 
catalog being defined. The catalog must be update password 
protected in order to prevent unauthorized users from 
cataloging data sets. 

When you anticipate using the catalog to contain many 
nonVSAM entries, you should consider allowing the catalog's 
update password to be null (that is, to specify a master 
password, but not an update password). A null update 
password allows you to alter and delete nonVSAM entries 
without having to supply the catalog's password. 

The phrase "an update- or higher-level password" means 5 

• If the update password exists, you ar& required to 
correctly supply either the update, control, or master 
password before Access Method Services processing 
cont i nues. 

• If the update password is null (that is, it does not 
exist), no prompting message i s issued and no password 
i s requi red. 

You can protect the catalog and its VSAM entries by 
specifying a master password. You can allow the 
unrestricted alteration and deletion of nonVSAM entries and 
the addition of all types of entries by not: specifying an 
update password. 

If a read password is the only password specified for the 
catalog (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei — level password and do not 
specify an update or read password, the update password is 
null. 

password 

is a 1 to 8 alphameric or special character password. 

If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 

When the password contains a special character (that 
is, a comma C,3, semicolon C;3, blank Cb], period C.3, 
single quote t'3, ampersand 1*1, plus sign [+3, equal 
sign C=3, hyphen C-3, parenthesis C( or )3, slash C/3, 
or asterisk C*3), enclose the password in 
single-quotation marks (for example, 
UPDATEPW('*DORIS*')). 

When the password contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation marks 
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(for example, UPDATEPWC »*CA ? f ROL* ' ) ) . 

You can code password in hexadecimal form, where two 
hexadecimal characters represent one alphameric or 
special character. For example, UPDATEPWCX' E2E4C5' ) is 
the same as UPDATEPW(SUE) . 

Abbreviation: UPDPW 

WRITECHECK 1 NOURITECHECK 

specifies whether the catalog is to be checked by a 
direct-access device operation called write-check when a 
record is written to the device. If WRITECHECK is 
specified, a record is written and then read, without data 
transfer, to test for the data check condition. 

Abbreviations: WCK and NWCK 



Components (Catalog) 



Attributes can be specified separately for the catalog's data 
and index components. 

DATAtopti onal parameters) 

specifies the data component's attributes. If an optional 
parameter is not specified as a parameter of DATA, the data 
component shares the value or attribute specified for the 
catalog as a whole. 

Except for space allocation, attributes specified as 
parameters of DATA override the same attributes specified 
as parameters of USERCATALOG. Attributes specified as 
parameters of DATA also override the same attributes of a 
model catalog's data component. 

Parameters that can be specified for the catalog's data 
component are : 

• BUFFERSPACE : Specifies the amount of buffer space that 
the user's program is to provide from its address space 
when the program opens the data component as a separate 
VSAM object. 

• CYLINDERS, RECORDS, or TRACKS: You can specify an 
amount of space to be allocated to the data component. 
You must also specify an amount of space for the 
catalog's data space. See the section "How Space is 
Assigned to a Catalog" for a description of the 
significance of specifying space allocation as a 
parameter of DATA. 

• RECOVERABLE or NOTRECOVERABLE: Specifies whether a 
catalog recovery area is to be created on each volume 
owned by the catalog. 

• WRITECHECK or NOWRITECHECK: Specifies whether the 
catalog's records ar^ to be checked by the 
direct-access device when they &re written into the 
data component. 

• DESTAGEWAIT or NODESTAGEWAIT : Specifies whether the 
catalog's data component, stored on a mass storage 
volume, is to be destaged synchronously or 
asynchronously with respect to the program that closes 
it. 

INDEXtopt i onal parameters) 

specifies the index component's attributes. If an optional 
parameter is not specified as a parameter of INDEX, the 
index component shares the value or attribute specified for 
the catalog as a whole. 



Command Format 263 



Except for space allocation, attributes specified as 
parameters of INDEX override the same attributes specified 
as parameters of USERCATALOG. Attributes specified as 
parameters of INDEX also override the same attributes of a 
model catalog's index component. 

Parameters that can be specified for the catalog's index 
component are : 

• CYLINDERS, RECORDS, or TRACKS: You can specify an 
amount of space to be allocated to the index component. 
When you specify one of the space-quantity parameters 
as a parameter of INDEX, you must also specify a 
space-quantity parameter as a parameter of DATA. 
TRACKS, CYLINDERS, or RECORDS must have been specified 
as a parameter of DATA to be specified as a parameter 
of INDEX. See the section "How Space is Assigned to a 
Catalog" for a description of the significance of 
specifying space allocation as a parameter of DATA and 
INDEX. 

• DESTAGEWAIT or NODESTAGEWAIT : Specifies whether the 
catalog's index component, stored on a mass storage 
volume, is to be destaged synchronously or 
asynchronously with respect to the program that closes 
it. 

• WRITECHECK or NOWRITECHECK: Specifies whether the 
index records are to be checked by the direct-access 
device when they are written into the index. 



Catalog (Catalog) 



The catalog parameter is used to supply the name and password, 
when required, of the master catalog when a user catalog is to 
be defined. 

CATALOG ( ma s t er cat name C /password] ) 

specifies the name and password of the master catalog. If 
the master catalog is password protected, its update- or 
higher-level password must be provided in this parameter or 
in response to prompting. 

mastercatname 

is the name of the master catalog that is required 
when a user catalog is being defined. 

password 

specifies the update- (or highei — level) password of 
the master catalog that is required when a user 
catalog is being defined, if the master catalog is 
password protected. 

Abbreviation: CAT 
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DEFINE USERCATALOG EXAMPLES 



Defining a User catalog and Determining the catalog's Space Requirements: 
Example 1 

In this example, a user catalog is defined. The user catalog's 
data space is not available to contain other VSAM objects. The 
catalog is to be large enough to contain information about 1 

100 key-sequenced clusters (that is, indexed VSAM data sets) 

10 entry-sequenced clusters (that is, sequential nonindexed 
VSAM data sets) 

5 key-sequenced clusters with alternate indexes to be 
upgraded 

5 entry-sequenced clusters with alternate indexes to be 
upgraded 

10 alternate indexes 

10 paths 

200 aliases 

10 generation data sets 

1000 nonVSAM data sets. 



5 volumes (the number to be controlled by the catalog) 
volume is a 3330 volume and contains 20 data spaces. 



Each 



To determine how much space, in records and tracks, is required 
for the primary allocation of a to-be-defined catalog in your 
system, see the section, "Estimating the Catalog's Space 
Requirements." The number of records for the primary allocation 
of the catalog in this example is shown in the completed 
worksheet in Figure 9. 

When you define the catalog's space parameters, use the 
following format: 

DEFINE USERCATALOG - 

(TRACKS(prvm seen) ... ) 



where* 



prim = the minimum amount of space for the catalog 
data-space's primary allocation. In this example, all of the 
data space is assigned to the catalog itself. The calculated 
value of prim should be rounded upward to the next whole 
number of tracks which is an even multiple of the catalog 
allocation unit for the device type being used (see the 
section "How Space is Assigned to a Catalog" for the size of 
an allocation unit). 

Because the catalog resides on a 3330 volume, the value of 

prim is= 

prim = .09N + 3 = 152.4 = = 153 tracks 
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Variable Quantities 



Basic requirement = 1 records 



A = 



B = 



K = 



M = 



number of key-sequenced clusters 

number of key-sequenced clusters with alternate 

indexes to be upgraded 

number of entry-sequenced clusters 

number of entry-sequenced clusters with alternate 

indexes to be upgraded 

number of relative-record clusters 

number of alternate indexes 

number of path entries 

number of nonVSAM data set entries 

number of generation data group entries 

number of alias entries 

number of page spaces 

number of volumes, depending on device type, 

owned by the catalog: . 

J 1 = number of 2305 volumes 

J 2 = number of 2314/2319 volumes 

J 3 = number of 3330 and 3340/3344 volumes 

J 4 = number of 3330 Model 1 1 and 3350 volumes 

for each key-sequenced cluster and alternate index 

(KSDS) with space on more than two volumes, add 

"1" for each additional group of one to five 

volumes: 

K 1 = number of KSDSs with 3 to 7 volumes 

K2 = number of KSDSs with 8 to 12 volumes 

K3 = number of KSDSs with 13 to 17 volumes 

for each entry-sequenced cluster and relative-record 

cluster (ESDS) with space on more than five 

volumes, add "1" for each additional group of one 

to eight volumes: 

L 1 = number of ESDSs with 6 to 1 3 volumes 

L 2 = number of ESDSs with 14 to 21 volumes 

for each group of four data spaces on a volume, 

add"l" 

number of entry records required for the catalog's 

data component (total of above) 



Formulas 



Kl 

K 2 x2 

K3x3 



Ll 

L 2 x2 

M 

N 
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Figure 9. Completed Worksheet for Determining a Catalog's Space 
Requi rements 



seen = the minimum amount of space for each secondary extent 
of the catalog's data space. 

The number of tracks required for the catalog's primary 
extent is at least 153. This figure is an even multiple of 
an allocation unit for a 3330 device (3); therefore* no 
further rounding is necessary. If VSAM extends the catalog* 
it should extend it in increments of 18 tracks. 

//DEFCAT1 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD x 

DEFINE USERCATALOGC - 

NAME(MYCAT) - 

VOLUMECVSER04) - 

N0TREC0VERABLE - 

TRACKSC153 18) ) - 
/x 
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The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE USERCATALOG command defines a user catalog. Its 
parameters are 1 

• NAME, which specifies the name of the catalog, MYCAT. 

• VOLUME, which specifies that the catalog is to reside on the 
volume whose serial number is VSER04. 

• NOTRECOVERABLE, which specifies that no recovery space is to 
be allocated for this catalog. 

• TRACKS, which specifies that the catalog's data space is to 
be 153 tracks. When the user catalog is extended, VSAM 
extends it in increments of 18 tracks. 

• . Values and attributes that apply by default to the catalog 

are J 

BUFFERSPACE = 3072 bytes 
ATTEMPTS = 2 
NOWRITECHECK 
NODESTAGEWAIT 

• Null attributes and values of the catalog are : 

All passwords 
CODE 

AUTHORIZATION 
TO and FOR 
OWNER 

Define a User Catalog Leaving Available Suballocatable Space: Example 2 

In this example, a user catalog is defined. The catalog will 
actually occupy only a portion of the space defined, leaving the 
remainder of the space available for the suballocat i on of other 
VSAM data sets. 

//DEFCAT2 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE USERCATALOGC - 

NAMECD27UCAT1) - 
MASTERPWCMRPWD27) - 
UPDATEPWCUPPWD27) - 
F0R(365) - 
CYLINDERSC150 5)) - 
VOLUMECVSER02) ) - 
DATA( - 

CYLINDERSC8 5) - 
INDEXC - 

CYLINDERS(S) ) - 
CATAL0GCAMASTCAT/MRCATPW2) 
/* 

The job control language statement is : 
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• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE USERCATALOG command defines a user catalog, D27UCAT1. 
Its parameters are- 

• NAME, which names the user catalog, D27UCAT1. 

• MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: MRPWD27 and UPPWD27 . 

• FOR, which specifies that the user catalog is to be retained 
for 365 days. 

• CYLINDERS, which specifies that 150 cylinders are to be 
allocated for the user catalog's data space. When the user 
catalog's data space is extended, it is to be extended in 
increments of 5 cylinders. 

• VOLUME, which specifies that the catalog is to reside on 
volume VSER02. Volume VSER02 will be dynamically allocated. 

• DATA and INDEX, which specify that VSAM is to allocate 13 
cylinders for the catalog itself. VSAM determines the 
proportion of space that is allocated to the catalog's data 
and index components. The remainder of the catalog's data 
space (137 cylinders) is available *to contain VSAM objects 
that reside in a nonunique data space. If the catalog's data 
component is extended, it is to be extended in increments of 
5 cylinders. The catalog's index component is never 
extended. 

• CATALOG, which specifies that the usei — catalog connector 
entry is to be defined in the master catalog, 
AMASTCAT. CATALOG provides the catalog's update password, 
MRCATPW2, so that the operator is not prompted to provide 
it. 

• Values and attributes that apply by default to the catalog 
are : 

BUFFERSPACE = 3072 bytes 

ATTEMPTS = 2 

NOTRECOVERABLE 

NOWRITECHECK 

NODESTAGEWAIT 

• Null attributes and values of the catalog are : 

CONTR0LPW and READPW passwords 
CODE 

AUTHORIZATION 
- OWNER 

Define a User Catalog using the MODEL Parameter: Example 3 

In this example, the user catalog defined previously, D27UCAT1, 
is used as a model for the user catalog being defined, D27UCAT2. 
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//DEFCAT3 


JOB 


//STEP1 


EXEC 


//STEPCAT 


DD 


//SYSPRINT 


DD 


//SYSIN 


DD 


DEFINE USE 



DEFINE USERCATALOG 



PGM=IDCAMS 

DSNAME=D27UCAT1,DISP=SHR 
SYSOUT=A 
* 
USERCATALOGC - 

NAMECD27UCAT2) - 
MASTERPW(MASTD27) - 
UPDATEPWCUPDD27) - 
CYLINDERS(50 5) - 
VOLUME(VSER03) - 
M0DEL(D27UCAT1/MRPUD27 - 
D27UCAT1/MRPWD27) ) - 
CATAL0GCAMASTCAT/MRCATPU2) 
/* 

The job control language statements are' 

• STEPCAT DD, which makes a catalog available for this job 
step: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE USERCATALOG command defines catalog D27UCAT2. Its 
parameters are'' 

• NAME, which names the catalog, D27UCAT2. 

• MASTERPW and UPDATEPU, which specify master and update 
passwords for the catalog: MASTD27 and UPDD27 

• CYLINDERS, which specifies that 50 cylinders are to be 
allocated for the catalog's data space. The catalog itself 
will reside within this data space. When the catalog's data 
space is extended, it is to be extended in increments of 5 
cyl i nders. 

• VOLUME, which specifies that the catalog is to reside on 
volume VSER03. Volume VSER03 will be dynamically allocated. 

• MODEL, which identifies D27UCAT1 as the catalog to use as a 
model for D27UCAT2. The attributes and specifications of 
D27UCAT1 that are not otherwise specified with the above 
parameters are used to define the attributes and 
specifications of D27UCAT2. D27UCAT1 contains the catalog 
entries that describe itself (the master catalog, AMASTCAT, 
contains a usei — catalog connector entry which points to 
D27UCAT1) — this is why D27UCAT1 is specified as MODEL'S 
catname subparameter . Values and attributes that apply to 
D27UCAT2 as a result of using D27UCAT1 as a model are- 

FOR = 365 days (retention period) 

CYLINDERS = 8 (primary) and 5 (secondary) for the data 
component and 5 (primary) for the index component 

BUFFERSPACE = 3072 bytes 

ATTEMPTS = 2 

NOTRECOVERABLE 

NOWRITECHECK 

NODESTAGEWAIT 

CONTROLPW and READPW passwords are null 

CODE i s null 
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AUTHORIZATION is null 
OWNER is null 

• CATALOG, which specifies that the user catalog connector is 
to be defined in the AMASTCAT catalog. The update password 
of AMASTCAT is MRCATPW2. 

Define a Recoverable User Catalog: Example 4 

In this example, a recoverable user catalog is defined. 

//DEFCAT4 JOB 

//STEP1 EXEC PGM=IDCAMS 

//V0L1 DD VOL=SER=VSER01,UNIT=2314,DISP=OLD 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE USERCATALOGC - 

NAMECD64CAT) - 

MASTERPW(UCATMRPW) - 

UPDATEPW(UCATUPPW) - 

T0(99999) - 

ATTEMPTSC3) - 

CODECBEQUIET) - 

RECOVERABLE - 

TRACKSC300) - 

FILE(VOLl) - 

VOLUME(VSEROl) ) -■ 
DATAC - 

RECORDSC500 100)) 
/* 

The job control language statements are: 

• V0L1 DD, which describes the volume on which the catalog is 
to be defined. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE USERCATALOG command defines a user catalog, D64CAT. 
Its parameters are: 

• NAME, which names the user catalog, D64CAT. 

• MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: UCATMRPW and UCATUPPW. 

• TO, which specifies that the user catalog is to be retained 
until it is deleted (that is, the user catalog does not have 
a retention period). 

• ATTEMPTS, which specifies that the operator is prompted for 
the correct password up to three times. 

• CODE, which specifies that the catalog is identified, in the 
prompting message to the operator, with the name, "BEQUIET." 

• RECOVERABLE, which specifies that the catalog's volumes 
contain catalog recovery areas and the LISTCRA, EXPORTRA, 
IMPORTRA, and RESETCAT commands can be used to restore 
entries in the catalog. 

• TRACKS, which specifies that 300 tracks are to be allocated 
for the user catalog's data space. No secondary allocation 
is specified. If additional VSAM space is required on the 
volume, it can be explicitly defined using the DEFINE SPACE 
command. 
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FILE, which points to the V0L1 DD statement. The. V0L1 DD 
statement directs the OS/VS Scheduler to mount and allocate 
the volume on which the user catalog is to reside. In this 
example, the volume is not dynamically allocated. 

VOLUME, which specifies that the user catalog is to reside 
on volume VSER01. 

DATA, which specifies that VSAM is to allocate space to 
accommodate 500 records for the user catalog. VSAM 
determines the total amount of space that is allocated to 
the catalog's data and index components. The remainder of 
the catalog's data space is available to contain the catalog 
recoverable area (CRA) and other VSAM objects that reside in 
a nonunique data space. If the catalog's data component is 
extended, it is extended in increments to accommodate 100 
records. 

You may wish to estimate the amount of space which VSAM will 
actually allocate to the catalog in order to : 

Ensure that the total amount of space specified via 
TRACKS is large enough 

Determine how much suballocatable space will be 
avai lable. 

You can make the computation by using the algorithms 
provided in the section "Estimating the Catalog's Space 
Requirements." Because the catalog resides on a-2314, the 
total amount of space will be : 

aN + b = (.1116 x 500) + 4 = 59.8 = 60 tracks 

Values and attributes that apply by default to the catalog 
are : 

BUFFERSPACE = 3072 bytes 

NOWRITECHECK 

NODESTAGEWAIT 

Null attributes and values of the catalog are: 

CONTROLPW and READPW passwords 

AUTHORIZATION 

OWNER 



Command Format 271 



DELETE 



The format of the DELETE command is : 



DELETE 



(entrynameC/passwordl Cb entrynameC/password] 
[ALIAS | 

ALTERNATEINDEXl 

CLUSTER} 

GENERATIONDATAGROUP | 

NONVSAM I 

PAGESPACEl 

PATH | 

SPACE | 

USERCATALOG] 
CERASElNOERASE] 
CFILE(dname)] 
[FORCE1NQFORCE3 
[PURGEI NQPURG E3 
[ SCRATCH I NQSCRATCH 3 

[CATALOG(catname[/password3 )3 



.3) 



DELETE may be abbreviated 5 DEL. 



DELETE PARAMETERS 



Required Parameters 



(en try name [/pa s sword 3 [b en try name. . . 3 ) 

names the entries to be deleted. If more than one entry is 
to be deleted, the list of entry names must be enclosed in 
parentheses. This parameter must be the first parameter 
following DELETE. 

entryname 

is the name of the entry to be deleted, or the volume 
serial number of the volume that contains a data space 
to be deleted. See the section "Generic Name and 
DELETE" for a description of how to specify a generic 
name in order to delete multiple entries with one 
entryname. 

If you are deleting a member of a nonVSAM partitioned 
data set, the entryname must be specified in the 
format 5 pdsname(membername) . 

password 

specifies a password for a password-protected entry. 
Passwords may be specified for each entry name or the 
catalog's password may be specified through the 
CATALOG parameter for the catalog that contains the 
entries to be deleted. Only certain types of catalog 
entries can be password-protected. To delete a 

• Alias, specify the catalog's update- (or 
highei — level) password. 

• Alternate index, specify its master password, or 
the catalog's master password. 

• Cluster, specify its master password, or the 
catalog's master password. 

• Generation Data Group, specify the catalog's 
update- (or highei — level) password. 

• NonVSAM entry, specify the catalog's update- (or 
higher-level) password. 
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Pagespace, specify its master password, or the 
catalog's master password. 

Path, specify its master password, or the 
catalog's master password. 

Data space, specify the catalog's update- (or 
highei — level) password. 

User catalog, specify its master password with the 
entryname (that is, Access Method Services does 
not issue a prompting message to the operator or 
TSO terminal user in this case). 



Optional Parameters 



ALIAS | ALTERNATEINDEX | CLUSTER | 

GENERATIONDATAGROUP | NONVSAM | PAGESPACE | PATH | 

SPACElUSERCATALOG 

specifies the type of the object or entry to be deleted. If 
the object to be deleted is a catalog or data space, 
USERCATALOG or SPACE is required. 

ALIAS 

specifies that the entry to be deleted is an alias 
entry. 

ALTERNATEINDEX 

specifies that the object to be deleted is an 
alternate index and its data and index entries. When a 
path entry is associated with the alternate index, the 
path entry is also deleted. When the alternate index 
has the to-be-upgraded attribute and it is the only 
such alternate index associated with the base cluster, 
the base cluster's upgrade-set entry is also deleted. 

Abbreviation: Aix 

CLUSTER 

specifies that the object to be deleted is a cluster, 
its associated data and index entries, and any related 
paths and alternate indexes. 

Abbreviation: CL 

GENERATIONDATAGROUP 

specifies that the entry to be deleted is a generation 
data group entry. A generation data group can be 
deleted when it is empty, or when you specify the 
FORCE parameter. Abbreviation: GDG 

NONVSAM 

specifies that the entry to be deleted is a nonVSAM 
data set entry. If the nonVSAM data set has aliases, 
all of its alias entries are deleted. If the nonVSAM 
data set is partitioned, you can delete one of its 
members by specifying pdsname (member name). 

Abbreviation: NVSAM 

PAGESPACE 

specifies that an inactive page space is to be 
deleted. A page space is identified as "active" during 
the operator's IPL procedure. 

Abbreviation: PGSPC 

PATH 

specifies that a path entry is to be deleted. No 
entries associated with the path are deleted. 
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SPACE 

specifies that all empty VSAM data spaces on a volume 
are to be deleted. This parameter is required when you 
want to delete the volume's empty data spaces. A data 
space can be deleted when it is empty , or when you 
specify the FORCE parameter. If all data spaces on the 
v volume have been deleted and the volume is not a 

candidate or catalog volume, its volume entry is also 
deleted. (Note: When a volume entry in the catalog is 
deleted, VSAM's ownership of the volume is 
relinquished.) When the catalog that owns the volume 
is recoverable^ the data space that contains the 
volume's recovery area is not deleted unless all other 
data spaces on the volume have been deleted. 

Abbreviation: SPC 

USERCATALOG 

specifies that the object to be deleted js a user 
catalog. The catalog connector entry in the master 
catalog is deleted. If the user catalog has aliases, 
all of the catalog's alias entries in the master 
catalog are deleted. This parameter must be specified 
if a user catalog is to be deleted. 

A user catalog can be deleted when it is empty (that 
is, it contains only its self-describing entries and 
its volume's volume entry), or when you specify the 
FORCE parameter. 

Abbreviation: UCAT 

CATALOGCcatnameC/password] ) 

specifies the name of the catalog that contains the entries 
to be deleted. See "Order of Catalog Use: DELETE" for 
information about the order in which catalogs ar^> searched. 
This parameter cannot be used when a user catalog is to be 
deleted. 

cat name 

identifies the catalog that contains the entry to be 
deleted. 

password 

specifies the password of the catalog that contains 
the entries to be deleted. If entries to be deleted 
are password protected and the catalog is also 
password protected, a password must be supplied either 
through CATALOG or with the name of each entry to be 
deleted. The password which must be specified for each 
entry type is given under the description of the 
entryname parameter. If a password is supplied through 
the CATALOG parameter, it takes precedence over any 
password supplied with the entryname parameter and is 
used for all entries to be deleted. If a user catalog 
is to be deleted, a password, if required, must be 
supplied with the entryname. 

Abbreviation: CAT 

ERASElNOERASE 

specifies whether the data component of a cluster or 
alternate index to be deleted is to be erased, that is, 
overwritten with binary zeros. This parameter will override 
whatever was coded when the cluster or alternate index was 
defined or last altered. This parameter should be specified 
only when a cluster or alternate index entry is to be 
deleted. When you specify ERASE, you must identify the 
to-be-deleted entry's catalog with a JOBCAT or STEPCAT DD 
statement unless 

♦ The entry is in the master catalog, or 
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• The first qualifier in the entry's qualified name 
identifies the catalog (that is, the first qualifier is 
the catalog's name or alias). 

ERASE 

specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
contains the data component must be mounted. 

Abbreviation: ERAS 

NOERASE 

specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 

Abbreviation: NERAS 

FILE(dname) 

specifies the name of the DD statement that identifies: 

• The volume that contains a unique data set to be 
deleted. 

• The volume that contains a nonVSAM data set to be 
deleted (with SCRATCH). 

• The entry (data set) to be deleted if erase processing 
is to be performed. (Note: For erase processing, a 
JOBCAT or STEPCAT DD statement is required unless the 
data set is cataloged in the master catalog or its high 
level qualifier is the name or alias of the catalog 
containing the entry.) 

• The volume that contains the data space to be deleted. 

• The partitioned data set from which a member (or 
members) is to be deleted. 

• The catalog recovery volume(s) when the entry being 
deleted is in a recoverable catalog. If the volumes are 
of a different device type, concatenated DD statements 
must be used. (The catalog recovery volume is the 
volume whose recovery space contains a copy of the 
entry being deleted. See "Deleting Catalog Entries" for 
more details on catalog recovery volume mounting 

requi rements. ) 

• The volume(s) owned by the catalog when you delete a 
catalog using the FORCE option. 

When more than one volume is to be identified (for example, 
a multivolume data set), FILE identifies the DD statement 
which specifies all volumes. If, in any of the above cases 
the volumes are of a different device type, concatenated DD 
second DELETE statements must be used. 

When deleting multivolume nonVSAM data sets with the 
SCRATCH option, DELETE SCRATCH processing will require 
access to each volume in the entry's catalog record before 
the scratch can be issued. This will require either all 
volumes to be mounted, online, and allocatable to' the job, 
or the use of the FILE parameter specifying a DD card 
allocating at least one mountable unit (not permanently 
resident or reserved). Deferred mount must be specified on 
the DD card so that allocation will flag the UCB to allow 
demount/mount requests to be issued for the unit as 
required during delete processing. If access to the volumes 
cannot be provided, then DELETE NOSCRATCH can be used to 
uncatalog the nonVSAM data set and the user will assume the 
responsibility of scratching the format-1 DSCBs from all 
the volumes. 
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In the following example nonVSAM data set 'TWO. TEST' exists 
on volumes TEST01, TEST02, TEST03, TEST04, TEST05, and 
TEST06. Only the first three volumes are mounted and online 
but TEST03 resides on a mountable unit. 



PGM=IDCAMS, REGION=400K 

DSN=USERCAT,DISP=SHR 

SYS0UT=A 

DSN=TWO.TEST,DISP=OLD, 
UNIT=(3330,3,DEFER), 
VOL=SER=(TEST01,TEST02,TEST0 3) 



//DLTB EXEC 
//STEPCAT DD 
//SYSPRINT DD 
//DD1 DD 
// 
// 

//SYSIN DD 
DELETE - 

TWO. TEST - 

NONVSAM - 

FILE(DDl) - 

PURGE - 

CATALOG(USERCAT) 
/x 

If you do not specify FILE and VSAM requires access to a 
volume or volumes during the delete processing, the 
volume(s) will be dynamically allocated. When erase 
processing is to be performed, the entryname will be 
dynamically allocated if FILE is hot specified. Dynamic 
allocation requires that the volume(s) must be mounted as 
permanently resident or reserved. 

FILE is required when deleting a nonempty user catalog 
using the FORCE option, and the catalog has data spaces 
residing on volumes other than the volume on which the 
catalog resides. 

FORCE | NOFORCI 

The FORCE parameter allows you to delete data spaces, 
generation data groups, and VSAM user catalogs without 
first ensuring that these objects are empty. 

• When you delete space using the FORCE parameter, all 
VSAM data spaces on the volume(s) are scratched from 
the VTOC. VSAM's ownership of the volume(s) is given 
up. Before the data spaces are scratched, VSAM verifies 
that no VSAM clusters on the volume are open. The 
clusters remain cataloged, but their entries are marked 
unusable. Subsequently, you can delete the cluster from 
the catalog. 

You cannot specify FORCE to delete the space on a 
volume that contains the VSAM master catalog or a user 
catalog. When you specify FORCE, you must supply the 
master password of the catalog that contains the 
volume's entry. 

• When you delete a user catalog using the FORCE 
parameter, the catalog is deleted even though it 
contains catalog entries for objects that haven't been 
deleted. All data spaces are deleted from each volume 
owned by the catalog. Before the data spaces are 
scratched, VSAM verifies that no VSAM clusters on the 
volume are open. The volumes are available to be used 
by the 0S/VS2 MVS system or to be assigned to other 
VSAM catalogs. All cataloged objects are automatically 
deleted, but the contents of each cluster and alternate 
index are not erased. NonVSAM data set entries in the 
catalog are deleted, but the nonVSAM data set's space 
on the volume is undisturbed. The nonVSAM data set can 
be located with its DSCB in the volume's VTOC. VSAM 
clusters and alternate indexes, even though they might 
reside in unique data spaces, cannot be located, 
because the data space's DSCB is scratched when the 
catalog is deleted. 
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When you delete a user catalog using the FORCE 
parameter* you must supply the master password of the 
catalog being deleted. 

• When you delete a generation data group using FORCE, 
the GDG entry is deleted even though it might point to 
generation data sets (that is, it might point to 
nonVSAM entries in the catalog). Each nonVSAM data set 
entry (that is, the entry for a generation data set) 
pointed to by the GDG base entry is deleted before the 
GDG base entry is deleted. However, the nonVSAM data 
set's space and contents on the volume is undisturbed. 
The data set can be located with its DSCB in the 
volume's VTOC. 

NOFORCE, the default option, causes the DELETE command to 
terminate when you request the deletion of a nonempty data 
space, generation data group, or catalog. 

Abbreviations: FRC and NFRC 

PURGE I NOPURGE 

specifies whether the entry is to be deleted regardless of 
the retention period specified. This parameter cannot be 
used if a data-space entry is to be deleted. 

PURGE 

specifies that the entry is to be deleted even if the 
retention period, specified in the TO or FOR 
parameter, has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the entry is not to be deleted if the 
retention period has not expired. If NOPURGE is coded 
and the retention period has not expired, the entry is 
not deleted. 

Abbreviation: NPRG 

SCRATCH 1N0SCRATCH 

has two uses 1 

1. With NONVSAM, SCRATCH | NOSCRATCH specifies whether a 
nonVSAM data set is to be scratched — removed from the 
VTOC — of the volume on which it resides. 

2. With CLUSTER, ALTERNATEINDEX, SPACE, or PAGESPACE, 
NOSCRATCH specifies that the entry is to be deleted 
from the catalog without access to the volume that 
contains the object defined by the entry. NOSCRATCH 
cannot be specified for VSAM clusters, alternate 
indexes, or page spaces in recoverable catalogs. See 
the section "VSAM Catalog Cleanup" in the chapter "Data 
Security and Protection" for important information 
about the use of DELETE NOSCRATCH. 

NOSCRATCH will be ignored when deleting the VSAM cluster 
entry (created for the source catalog) on the receiving 
catalog's volume as a result of the copy catalog operation. 
See the section "Copy-Catalog Procedure" in the chapter 
"Copying and Printing" for more detailed information. 

When you specify SCRATCH, you must identify the 
to-be-deleted entry's catalog with a JOBCAT or STEPCAT DD 
statement, unless: 

• The entry is in the master catalog, or 

• The first qualifier in the entry's qualified name 
identifies the catalog (that is, the first qualifier is 
the catalog's name or alias). 
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You should specify NOSCRATCH if the format-1 DSCB of a 
nonVSAM data set has already been scratched from the VTOC. 

You should specify NOSCRATCH if you are deleting a nonVSAM 
data set which was defined with an esoteric device type 
(for example, SYSDA). If you specify SCRATCH, your DELETE 
will fail. You should use the SCRATCH function of the OS/VS 
utility, IEHPROGM, to remove the format-1 DSCB from the 
VTOC. 

Abbreviations: SCR and NSCR 
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DELETE EXAMPLES 

Deleting a Key-sequenced VSAM Cluster: Example 1 

In this example, a key-sequenced cluster is deleted. Alternate 
indexes and paths related to the key-sequenced cluster are 
deleted automatically by Access Method Services. Access Method 
Services will dynamically allocate the key-sequenced data set so 
that the data can be overwritten (as specified by the ERASE 
opti on) . 

//DELET1 JOB 
//STEP1 EXEC PGM=IDCAMS 
| //JOBCAT DD DSN=D27UCAT2,DISP=0LD 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD x 
DELETE - 

D40. EXAMPLE. KSDS1 - 

PURGE - 

ERASE - 

CATAL0GCD27UCAT2/MRPWD27) 
/x 

The job control language statement is? 

J • JOBCAT DD, which makes a catalog available for the job: 
1 D27UCAT2. 

• SYSPRINT DD, which is required in all Access -Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer sr& to be sent. 

The DELETE command deletes the key-sequenced VSAM cluster from 
the D27UCAT2 catalog. Its parameters are: 

• D40. EXAMPLE. KSDS1, which is the entryname of the object 
being deleted. D40 . EXAMPLE. KSDS1 is a key-sequenced VSAM 
cluster. 

• PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. 

• ERASE, which specifies that the cluster's data component is 
to be overwritten with binary zeros, regardless of a NOERASE 
attribute that might have been specified when the cluster 
was defined or altered. 

• CATALOG, which identifies the catalog that contains the 
cluster's entries, D27UCAT2. The catalog's master password 
is required, unless the entry's master password is specified 
with the entryname. 
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Deleting an Entry-Sequenced VSAM Cluster and All Empty Data Spaces On a Volume: 
Example 2 

In this example* an entry-sequenced VSAM cluster is deleted. 
Alternate indexes and paths related to the entry-sequenced 
cluster are automatically deleted by Access Method Services. 
Next, all empty VSAM data spaces on volume VSER03 are deleted 
and the volume's volume entry is deleted. 

//DELET2 JOB ... 

//JOBCAT DD DSNAME=D27UCAT2,DISP=0LD 
//STEP1 EXEC PGM=IDCAMS 

//DD2 DD VOL=SER=VSER03,UNIT=3330*DISP=OLD 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE. ESDS2/DEPT26M - 

PURGE - 

CLUSTER 
DELETE - 

VSER03 - 

SPACE - 

FILE (DD2) 

The job control language statements &r&' 

• JOBCAT DD* which makes a catalog available for the job : 
D27UCAT2. 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The first DELETE command deletes the only VSAM cluster on volume 
VSER03. The DELETE command's parameters are: 

• EXAMPLE. ESDS2* which is the entryname of the cluster to be 
deleted* and DEPT26M* which is the cluster's master 
password. 

• PURGE* which specifies that the cluster is to be deleted 
regardless of its retention period or date. Alternate 
indexes and paths related to the entry-sequenced cluster are 
also deleted regardless of their retention periods or dates. 

• CLUSTER* which specifies that the entryname EXAMPLE. ESDS2 
identifies a VSAM cluster (that is* the entryname identifies 
a cluster entry). 

The second DELETE command causes VSAM to examine each data space 
cataloged in the volume's entry and* if the data space is empty* 
delete the data space. VSAM deletes the volume entry when there 
are no data spaces cataloged in it and when there are no data 
sets identified that specify the volume as a candidate volume. 
VSAM also updates the volume's VTOC to reflect the deleted data 
spaces. The DD2 DD statement ensures that volume VSER03 is 
mounted when its data spaces are deleted. In this example JCL 
has been used instead of allowing Access Method Services to 
dynamically allocate the volume. If the volume were mounted as 
permanently RESIDENT or RESERVED* Access Method Services could 
dynamically allocate the volume without the need of JCL or the 
FILE parameter. The DELETE command's parameters are: 

• VSER03* which identifies the volume that contains empty VSAM 
data spaces. 

• SPACE* which specifies that the entryname identifies a 
volume entry. When a volume's data spaces are to be deleted, 
the SPACE parameter is required. 

• FILE* which specifies the dname of a DD statement that 
describes the VSAM volume and causes it to be mounted. 
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Deleting Two Key-sequenced Clusters: Example 3 



In this example* two key-sequenced clusters* D40.MYDATA and 
ENTRY* are deleted from a recoverable catalog. This example 
illustrates how more than one cataloged object is deleted with a 
single DELETE command. 



//DELET3 JOB 


• * ♦ 


//JOBCAT DD 


DSNAME=MYCAT*DISP=SHR 


//STEP1 EXEC 


PGM=IDCAMS 


//SYSPRINT DD 


SYS0UT=A 


//SYSIN DD 


X 


DELETE - 




(D40.MYDATA - 


ENTRY) 


- 


PURGE • 




CLUSTER 


/* 





The job control language statements are : 

• JOBCAT DD, which makes the catalog MYCAT available for the 
job. 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DELETE command deletes the key-sequenced clusters D40.MYDATA 
and ENTRY. The high-level qualifier of the object D40.MYDATA 
causes the catalog D27UCAT1 to be searched* since it is assumed 
that D40 is an alias of the catalog D27UCAT1. The object ENTRY 
is found in the catalog MYCAT* which is made available to the 
job through the JOBCAT DD statement. Both entries will be 
dynamically allocated so that their respective catalog recovery 
areas can be updated. The DELETE command's parameters are : 

• D40.MYDATA and ENTRY* which identify the objects to be 
deleted. D40.MYDATA and ENTRY are the entrynames of two 
key-sequenced clusters. It is assumed that neither cluster 
is password-protected at this time. If either cluster is 
password-protected, the operator is prompted to supply the 
cluster's master password. 

• PURGE* which specifies that the cluster is to be deleted 
regardless of its retention period or date. 

• CLUSTER* which specifies that D40.MYDATA and ENTRY are 
clusters (that is* the names identify cluster catalog 
records) . 

Deleting a NonVSAM Data Set's Entry: Example <t 

In this example* a nonVSAM data set's entry (cataloged in a VSAM 
user catalog) is deleted. The SCRATCH parameter is implied (that 
is* it is the default). A FILE parameter and its associated DD 
statement ar& provided to allocate the data set's volume. In 
this example* dynamic allocation is not used to provide catalog 
or volume allocation. 
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//DELETE 


JOB 


//JOBCAT 


DD 


//STEP1 


EXEC 


//DD1 


DD 



DSNAME=D27UCAT1,DISP=SHR 
PGM=IDCAMS 

VOL=SER=VSER02,UNIT=2314,DISP=OLD, 
// DSNAME=EXAMPLE. NONVSAM 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE. NONVSAM - 
FILE (DD1) - 
PURGE - 

CATAL0GCD27UCAT1/UPPWD27) 
/x 

The job control language statements are'' 

• JOBCAT DD, which makes a catalog available for this job? 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DELETE command deletes the nonVSAM data set EXAMPLE. NONVSAM. 
The DELETE command's parameters are: 

• EXAMPLE. NONVSAM, which is the entryname of the object to be 
deleted. 

• FILE, which specifies the dname of a DD statement that 
describes the nonVSAM data set's volume and causes it to be 
mounted. When the data set is deleted, its DSCB entry in the 
volume's VTOC is removed. 

• PURGE, which specifies that the nonVSAM data set's retention 
period or date is to be ignored. If PURGE is not specified 
and the nonVSAM data set's retention period has not yet 
expired, VSAM wouldn't delete its entry. 

• CATALOG, which identifies the catalog that contains the 
entries, D27UCAT1, and its update password, UPPWD27 . 

Deleting Nonempty VSAM Data spaces on a Volume: Example 5 

In this example, all of the data spaces on volume VSER05 are 
deleted, whether or not they are empty. All VSAM data spaces on 
the volume are scratched from the VTOC and the ownership of the 
volume is surrendered by the catalog, AMASTCAT. Any clusters or 
alternate indexes contained within, the data spaces on volume 
VSER05 are marked unusable in the catalog. Because all VSAM data 
spaces on the volume are deleted, the volume's catalog entry is 
also deleted. 

//DELET5 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

VSER05 - 

SPACE - 

FORCE - 

CATAL0GCAMASTCAT/MRCATPW2) 
/* 

The job control language statements are* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 
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The DELETE command's parameters are- 



VSER05, which identifies the volume with its serial number. 
Because the volume's VTOC must be updated. Access Method 
Services will dynamically allocate the volume. 

SPACE* which specifies that a volume entry is to be modified 
or deleted. When a volume's data space i s to be deleted, the 
SPACE parameter is required. 

FORCE, which specifies that all VSAM data spaces on the 
volume are to be deleted, whether or not they are empty, and 
that volume ownership is to be released. 

CATALOG, which identifies the catalog that owns the volume, 
AMASTCAT. The catalog's update (or higher level) password is 
requi red. 



Deleting a User Catalog: Example 6 



In this example, a user catalog is deleted. A user catalog can 
be deleted when it is empty — that is, when there are no objects 
except the catalog's volume cataloged in it. If the catalog is 
not empty, it cannot be deleted unless the FORCE parameter is 
specified. 

//DELET6 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

D27UCAT1/MRPWD27 - 

PURGE - 

USERCATALOG 
/* 

The DELETE command deletes the catalog. The volume that 
contained the catalog is now available for ownership by another 
VSAM catalog. The DELETE command also deletes the catalog's user 
catalog connector entry in the master catalog. The DELETE 
command's parameters are : 

• D27UCAT1, the name of the user catalog. The catalog's update 
(or higher level) password is required. 

• PURGE, which specifies that the user catalog's retention 
period or date is to be ignored. If PURGE is not specified 
and the catalog's retention period has not yet expired, it 
won't be deleted. 

• USERCATALOG, which identifies D27UCAT1 as a user catalog. 



Deleting an Alias Entry: Example 7 



In this example, an alias entry, EXAMPLE. N0NVSAM1 , is removed 
from catalog D27UCAT1. 

//DELET7 JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=0LD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE. N0NVSAM1 - 

ALIAS - 

CATAL0G(D27UCAT1/MRPWD27) 
/x 
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The job control language statements are : 

• JOBCAT DD, which makes a catalog available for this job' 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DELETE command removes an alias entry from catalog D27UCAT1. 
Its parameters are: 

• EXAMPLE. N0NVSAM1, the entryname of the object to be deleted. 
EXAMPLE. N0NVSAM1 identifies an alias entry. 

• ALIAS, which specifies the type of entry to be deleted. VSAM 
verifies that EXAMPLE. N0NVSAM1 is an alias entry, then 
deletes it. If EXAMPLE. N0NVSAM1 incorrectly identified 
another entry by mistake, VSAM would not delete the entry, 
but would note the discrepancy with a message to the 
programmer. 

• CATALOG, which identifies the catalog that contains the 
entry, D27UCAT1, and its master password, MRPWD27 . 

Deleting Generics lly-Named Entries: Example 8 

In this example, each catalog entry with the name 
"GENERIC*. ABLE" is deleted, where "*" is any 1- to 8-character 
simple name. The name "GENERIC. *. ABLE" is a generic name, and 
this example shows how all catalog entries with the same generic 
name are deleted. 

//DELET8 JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=0LD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

GENERIC*. ABLE - 

PURGE - 

CATAL0GCD27UCAT1/MRPWD27) 
/* 

The job control language statements are' 

• JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DELETE command removes all entries (and their associated 
entries) with the generic name "GENERIC *. ABLE" from catalog 
D27UCAT1. Its parameters are- 

• GENERIC*. ABLE, a generic name, identifies all catalog 
entries with the name GENERIC* .ABLE. 

• PURGE, which specifies that each entry is to be purged 
regardless of the retention period or date specified when it 
was def i ned. 

• CATALOG, which identifies the catalog that contains the 
entries, D27UCAT1, and its master password, MRPWD27. 
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List a Generation Data Group's Entries, Then Delete the Group and Its Data 
Sets: Example 9 

In this example, a generation data group, GDG01, and its 
associated (generation data set) entries are listed. Next, the 
only generation data set in the group is deleted. Finally, the 
generation data group base catalog entry is deleted. 

//DELET9 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
LISTCAT - 

ENTRIES(GDGOl) - 

ALL 
DELETE - 

GDG01.G0001VOO - 

PURGE 
DELETE - 

GDG01 - 

GENERATIONDATAGROUP - 

PURGE 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

Because no catalog was specified in a CATALOG parameter or with 
a JOBCAT or STEPCAT DD statement, VSAM assumes all entries 
required for this command sequence are in the master catalog. 

The LISTCAT command lists the generation data group GDG01 and 
its associated generation data set entries. Its parameters are' 

• ENTRIES, which specifies that the entry GDG01 is to be 
listed. Since the entry GDG01 is a generation data group 

ep X_.. _-J._ Z.J..., J..-- ...J-- __J.,_ ,„__l,„A^ 

et 

g< 

associated with the generation data set's entry are listed 

• ALL, which specifies that all fields are to be listed 

The first DELETE command removes the nonVSAM data set entry for 
the only generation data set in the generation data group* 
GDG01 .G0001VOO. Its parameters are'- 

• GDG01 .G0001VOO, the entryname of the object being deleted. 
GDG01.G0001V00 identifies the only generation data set in 
the generation data group GDG01. 

• PURGE, which specifies that the generation data set's 
retention period or date is to be ignored. If PURGE is not 
specified and the generation data set's retention period has 
not yet expired, VSAM wouldn't delete its entry. 

The second DELETE command removes the generation data group base 
catalog entry from the catalog. Its parameters are- 

• GDG01, the entryname of the object being deleted. GDG01 
identifies the generation data group base entry. 

• GENERATIONDATAGROUP, which specifies the type of entry to be 
deleted. VSAM verifies that GDG01 is a generation data group 
entry, then deletes it. If GDG01 incorrectly specified 
another type of entry, VSAM would not delete the entry, but 
would note the discrepancy with a message to the programmer. 
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• PURGE, which specifies that the generation data group's 

retention period or date is to be ignored. If PURGE is not 
specified and the generation data group's retention period 
has not yet expired, VSAM wouldn't delete its entry. 

Deleting a Member of a Partitioned (NonVSAM) Data Set: Example 10 

In this example, the MEM1 member of partitioned data set 
EXAMPLE. N0NVSAM2 is deleted. Next, the nonVSAM data set itself 
i s deleted. 



//DELET10 


JOB 


• * • 


//JOBCAT 


DD 


DSNAME=D27UCAT1,DISP=SHR 


//STEP1 


EXEC 


PGM=IDCAMS 


//SYSPRINT DD 


SYS0UT=A 


//SYSIN 


DD 


X 


DELETE - 






EXAMPLE 


.N0NVSAM2CMEM1) - 




CATAL0GCD27UCAT1/MRPUD27) 


DELETE - 






EXAMPLE, 


.N0NVSAM2 - 




PURGE - 






CATAL0GCD27UCAT1/MRPWD27) 



/X 

The job control language statements are'' 

• JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The first DELETE command deletes one of the members of a 
partitioned data set, EXAMPLE. N0NVSAM2CMEM1) , from the user 
catalog D27UCAT1. Its parameters are'' 

• EXAMPLE. N0NVSAM2CMEM1), which is the entryname of one of the 
members of the partitioned (nonVSAM) data set, 

EXAMPLE. N0NVSAM2. The entryname identifies the object to be 
deleted. 

• CATALOG, which identifies the catalog that contains the 
entry, D27UCAT1, and its master password, MRPWD27. 

The second DELETE command deletes all remaining members, as well 
as the data set itsel-f, of the partitioned nonVSAM data set 
EXAMPLE. N0NVSAM2. Its parameters are: 

• EXAMPLE. N0NVSAM2, which is the entryname of the object to be 
deleted. 

• PURGE, which specifies that the nonVSAM data set's retention 
period or date is to be ignored. If PURGE had not been 
specified and the nonVSAM data set's retention period has 
not yet expired, VSAM wouldn't delete its entry. 

• CATALOG, which identifies the catalog that contains the 
entry, D27UCAT1, and its master password, MRPWD27 . 

In the second part of this example, the DSCB entry in the 
volume's VTOC i s removed. Dynamic allocation is used to allocate 
the data set's volume. 
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Deleting a Page Space: Example 11 

In this example, page space SYS1.PAGE2 is deleted. 

//DELET11 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
DELETE - 

SYS1.PAGE2 - 

PURGE - 

PAGESPACE 
/* 

The job control language statement is«* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DELETE command removes a page space entry, SYS1.PAGE2, from 
the master catalog. Its parameters are'* 

• SYS1.PAGE2, the entryname of the object to be deleted. 
SYS1.PAGE2 identifies a page space entry. 

• PURGE, which specifies that the page space entry is to be 
deleted regardless of the retention period or date specified 
when it was defined. 

• PAGESPACE, which specifies the type of entry to be deleted. 
VSAM verifies that SYS1.PAGE2 is a page space entry, then 
deletes it. If SYS1.PAGE2 incorrectly identified another 
type of entry, VSAM would not delete it, but would send an 
error message to the programmer. 
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EXPORT 



The format of the EXPORT command* when it is used to disconnect 
a user catalog, is : 



EXPORT 



usercatnameE /password 3 
DISCONNECT 



The format of the EXPORT' command, when it is used to move a 
cluster or alternate index, is: 



EXPORT 



entrynamet /password 3 

{OUTFILE(dname)|OUTDATASET(entryname)} 

[INFILECdname)] 

CERASEIN0ERASE3 

[INHIBITS0URCE1 N0INHIBITS0URCE 3 

[INHIBITTARGETI N0INHIBITTARGET 3 

[PURGEI NQPURGE 3 

[TEMPORARY I PERMANENT 3 



EXPORT PARAMETERS 



Required Parameters 



entrynameC/pas 
i s a requ 
index, or 
be the fi 
exporti ng 
higher le 
exporti ng 
(the obje 
paths are 
exported, 
catalog c 
protecti o 



sword3 

i red parameter that names the cluster, alternate 

user catalog to be exported. This parameter must 
rst parameter following EXPORT. If you are 

a user catalog, you must supply the update (or 
vel) password of the master catalog. If you are 

a cluster or alternate index, you must supply its 
ct's) master password. If any password-protected 

defined over the cluster or alternate index being 

you must supply the master password of the 
ontaining the objects in order to export the 
n attributes of all the paths. 



Abbreviation: EXP 

DISCONNECT 

specifies that a user catalog is to be exported. The entry 
for the user catalog will be deleted from the master 
catalog. Also, the user catalog's alias entries are deleted 
from the master catalog. 

A JOBCAT/STEPCAT can be used to delete a user catalog entry 
from a user catalog. Any alias entries will also be 
deleted. 

DISCONNECT is a required parameter if EXPORT is issued for 
a user catalog. The volume that contains the user catalog 
can be physically moved to the system to which the catalog 
will be imported. 

If DISCONNECT is coded, the entry name and the master 
catalog's update or highej — level password, and no other 
parameters, must be coded with it. To make a user catalog 
available in other systems and in the original system, code 
the IMPORT command to import the user catalog to each 
system to which it is to be available, but do not EXP0,RT 
the user catalog. 

Abbreviation: DCON 

OUTFILE(dname) 

specifies the name of the DD statement that identifies the 
output data set to be created as a result of the EXPORT 
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EXPORT 

command. With the exception of blocksize, the data set 
characteristics of the output data set that is to contain 
the cluster to be exported should not be specified. The 
characteristics of the output data set are described in the 
section "Moving Entries." 

Blocksize is defaulted by the EXPORT command to 2048. 
Blocksize may be specified in the DD statement to override 
this default and improve performance. 

Abbreviation: OFILE 

OUTDATASET ( ent ryname ) 

specifies the name of the data set that is to receive the 
data being exported. If OUTDATASET is specified, the 
entryname is dynamically allocated. The characteristics of 
the output data set are described in the section "Moving 
Entri es. " 

Abbreviation: ODS 



Optional Parameters 



ERASElNOERASE 

specifies whether the data component of the cluster or 
alternate index to be exported is to be erased (that is, 
overwritten with binary zeros). This parameter overrides 
whatever was specified when the object was defined or last 
altered. This parameter can be specified only if the object 
is to be permanently exported (that is, deleted from the 
original system). 

Abbreviations: ERAS and NERAS 

INFILEtdname) 

specifies the name of the DD statement that identifies the 
cluster or alternate index to be exported. If the cluster 
or alternate index has been defined with a maximum logical 
record length greater than 32,760 bytes, EXPORT processing 
terminates with an error message. 

In addition to the DD statement for INFILE, you must 
identify the entry's catalog with a JOBCAT or STEPCAT DD 
statement unless 1 

• The object's entry is in the master catalog, or 

• The first qualifier of the object's name identifies a 
catalog (that is, the first qualifier is the catalog's 
name or alias) . 

When INFILE and its DD statement aren't specified for a 
to-be-exported object, it is dynamically allocated. 

Abbreviation: IFILE 

INHIBITSOURCE 1 NOINHIEITSOURCE 

specifies whether the original data records (that is, the 
data records of the source cluster or alternate index) can 
be accessed for any operation other than retrieval after 
its copy is exported. This specification can later be 
altered through the ALTER command. 

INHIBITSOURCE 

specifies that the source object in the original 
system cannot be accessed for any operation other than 
retrieval. This parameter can be specified only when 
the object is to be temporarily exported (that is, a 
backup copy of the object is made; the object itself 
remains in the original system). 

Abbreviation: INHS 
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NOINHIBITSOURCE 

specifies that the source object in the original 
system can be accessed for any kind of operation. 

Abbreviation: NINHS 

INHIBITTARGET I NOINHIBITTARGET 

specifies whether the copy's records (that is, the target 
alternate index or cluster) can be accessed for any 
operation other than retrieval after it has been imported 
to another system. This specification can be altered 
through the ALTER command. 

INHIBITTARGET 

specifies that the target object cannot be accessed 
for any operation other than retrieval after it has 
been imported into another system. 

Abbreviation: INHT 

NOINHIBITTARGET 

specifies that the target object can be accessed for 
any type of operation after it has been imported into 
another system. 

Abbreviation: NINHT 

PURGEl NOPURGE 

specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system 
regardless of the retention period, specified in a TO or 
FOR parameter when the object was defined. This parameter 
can be specified only if the object is to be permanently 
exported, that is, deleted from the original system. 

PURGE 

specifies that the object is to be deleted even if the 
retention period has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the object is not to be deleted unless 
the retention period has expired. 

Abbreviation: NPRG 

TEMPORARY I PERMANENT 

specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system. 

TEMPORARY 

specifies that the cluster or alternate index is not 
to be deleted from the original system. The object in 
the original system is marked as temporary to indicate 
that another copy exists and that the original copy 
can be replaced. To replace the original copy, a 
portable copy created by an EXPORT command must be 
imported to the original system. The IMPORT command 
deletes the original copy, defines the new object, and 
copies the data from the portable copy into the newly 
defined object. 

Abbreviation: TEMP 

PERMANENT 

specifies that the cluster or alternate index is to be 
deleted from the original system. Its storage space is 
freed. If its retention period has not yet expired, 
you must also code PURGE. 

Abbreviation: PERM 
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EXPORT 
EXPORT EXAMPLES 



Exporting a Key-Sequenced Cluster: Example 1 



In this example, a key-sequenced cluster, D40 . EXAMPLE. KSDS1 , is 
exported from a user catalog, D27UCAT1. The cluster is copied to 
a portable file, TAPE2, and its catalog entries ar& modified to 
prevent the cluster's data records from being updated, added to, 
or erased. 

//EXP0RT1 JOB 
//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE2, UNIT=(2400-3, , DEFER) , 
// DISP=NEW,VOL=SER=003030, 
// DCB=(BLKSIZE=6 0,DEN=3),LABEL=(1,SL) 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
EXPORT - 

D40. EXAMPLE. KSDS1 - 

OUTFILE(RECEIVE) - 

TEMPORARY - 

INHIBITSOURCE 
/* 

The job control language statements are: 

• RECEIVE DD, which describes the portable file, a magnetic 
tape file, that is to receive a copy of the cluster's 
records. The DCB BLKSIZE parameter overrides the EXPORT 
default of 2048 to improve performance. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The EXPORT command copies the key-sequenced cluster, 

D40. EXAMPLE. KSDS1, to a portable file, TAPE2, and modifies the 

cluster's catalog entries (its cluster, data, and index 

entries). Access Method Services dynamically allocates 

D40. EXAMPLE. KSDS1. Since the high-level qualifier of the cluster 

name is the name of the alias of D27UCAT2, the cluster can be 

allocated without specifying a JOBCAT or STEPCAT DD statement. 

The EXPORT command's parameters are : 

• D40. EXAMPLE. KSDS1, which identifies the cluster to be 
exported. Because the cluster is not password protected, no 
password is provided with the cluster's entryname. 

• OUTFILE, which points to the RECEIVE DD statement. The 
RECEIVE DD statement describes the portable file, TAPE2, 
that is to contain a copy of the cluster. 

• TEMPORARY, which specifies that the cluster is not to be 
deleted.* The cluster's catalog entry is marked "temporary" 
to indicate that another copy of the cluster exists and that 
the original copy can be replaced. (See the IMPORT Example 
2, "Importing a Key-Sequenced Cluster.") 

• INHIBITSOURCE, which specifies the cluster (that is, the 
copy of it that remains in the original system, as a result 
of TEMPORARY) cannot be modified. User programs are allowed 
only to read the cluster's records. 

Exporting an Entry-Sequenced Cluster: Example 2 

In this example, an entry-sequenced cluster is exported to a 
portable file and then it is deleted from the system. 
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//EXP0RT2 JOB 
//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE1 , UNIT=(2400-3, , DEFER) , 
// VOL=SER=001147,LABEL=(1,SL),DISP=NEW 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
EXPORT - 

D50. EXAMPLE. ESDS1/DEPT26M - 

OUTFILE(RECEIVE) - 

PURGE 
/* 

The job control language statements are: 

• RECEIVE DD, which describes the portable file, TAPE1, that 
is to contain a copy of the exported entry-sequenced 
cluster. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The EXPORT command copies the entry-sequenced cluster, 
D50. EXAMPLE. ESDS1, to a portable file, TAPE1. The cluster is 
deleted from the system after it is copied into the portable 
file. Access Method Services dynamically allocates 
D50. EXAMPLE. ESDS1. Since the high-level qualifier of the cluster 
-is the name of the alias of the catalog D27UCAT2, the cluster 
can be dynamically allocated without specifying a JOBCAT or 
STEPCAT DD statement. The EXPORT command's parameters are' 

• D50 . EXAMPLE. ESDS1 , which identifies the entry-sequenced 
cluster to be exported, and which specifies the cluster's 
master password, DEPT26M. When a cluster is exported, its 
master password is required if it is password protected. 

• OUTFILE, which points to the RECEIVE DD statement. The 
RECEIVE DD statement describes the portable data set, TAPE1, 
that is to receive a copy of the cluster. 

• PURGE, which allows the cluster to be deleted regardless of 
its retention period or date. 

Because TEMPORARY is not specified, Access Method Services 
assumes the cluster is to be deleted once TAPE1 contains a copy 
of it. 

Because INHIBITTARGET i s not specified, Access Method Services 
assumes the cluster can be updated (by users of the other 
system) when it is imported to another system. 



Exporting a User catalog: Example 3 



In this example, the user catalog D27UCAT1 is exported — that is, 
it ts disconnected from the system. Its cataloged objects are no 
longer available to users of the system. 

//EXP0RT3 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
EXPORT * 

D27UCAT1/MRPWD27 - 

DISCONNECT 
/K 

The job control language statement is: 

♦ SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 
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EXPORT 

The EXPORT command removes the user catalog connector entry for 
D27UCAT1 from the master catalog. The catalog becomes 
unavailable to system users until the system programmer 
reconnects it to the system, using an IMPORT CONNECT command. 
The EXPORT command's parameters are: 

• D27UCAT1, which identifies the object to be exported. When a 
user catalog is exported* the master catalog's master 
password is required. (See IMPORT Example 1, "Import a User 
Catalog.") 

• DISCONNECT, which identifies the exported object as a user 
catalog. When a user catalog is exported, DISCONNECT is 
requi red. 
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EXPORTRA 



The format of the EXPORTRA command is: 



EXPORTRA 


OUTFILE(dname) 
CRA( 

(dnamel 

(ALLCb INFILE(dname2)3| 
ENTRIES ( 

(entrynameCb dname33) 






C (entrynameCb dname33).. 


.3)1 




NOME) ) 






[ (dnamel. ..)... 3 ) 






[FORCE IN0F0RCE3 






CMASTERPW(password)3 





EXPORTRA may be abbreviated: XPRA 



EXPORTRA PARAMETERS 



Required Parameters 



OUTFILE(dname) 

identifies the DD statement tha 
(usually a movable disk pack or 
to contain a copy of the VSAM o 
identified with the CRA paramet 
blocksize, the data set charact 
set that is to contain the clus 
not be specified. The character 
set are described in the sectio 
from the Catalog Recovery Area, 
the EXPORTRA command to 2048. B 
the DD statement to override th 
performance. 

Abbreviation: OFILE 



t describes the data set 

magnetic tape reel) that is 
bjects and catalog entries 
er. With the exception of 
eristics of the output data 
ter to be exported should 
i sties of the output data 
n "Copying a Catalog Entry 
" Blocksize is defaulted by 
locksize may be specified in 
is default and improve 



CRA( 

(dnamel 

{ALLCb INFILE(dname2)3| 
ENTRIES( 

(entrynameCb dname33) 
[(entrynameCb dname33 ). . . 3 ) I 
NONE} ) 
C (dnamel ...)... 3 ) 

The CRA parameter and its subparameters describe the 
catalog recovery area to be referred to, identify the 
specific entries to be copied from the catalog recovery 
area, and specify the volumes that contain the entries' 
data. The subparameters are repeated to describe each 
catalog recovery area to be referred to* and whether its 
entries are to be copied. 

dnamel 

identifies the DD statement that describes a volume 
whose catalog recovery area is to be referred to. Each 
dnamel you specify is followed by one of the following 
subparameters which specifies the action to be taken 
with regard to the catalog recovery area : 



ALL 



specifies that each entry in dnamel T s catalog 
recovery area is to be copied to the OUTFILE data 
set. In addition, the contents (that is, data 
records in logical sequential order) of each VSAM 
cluster and alternate index are copied, following 
the copy of the catalog recovery area entry. If 
any of these VSAM clusters or alternate indexes 
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EXPORTRA 



has data which resides on volumes other than that 
identified via dnamel, you use INFILE to describe 
all the volumes. 

INFILE(dname2) 

identifies the DD statement that describes 
multiple volumes to be used in the recovery 
process. INFILE is required if the VSAM clusters 
and/or alternate indexes whose entries are 
contained in dnamel ' s catalog recovery area 
reside on multiple volumes, in addition to the 
dname2 DD' statement, including the volume 
referenced by the dnamel DD statement. 

Abbreviation: IFILE 

ENTRIES ( 

(entrynameCb dname3]) 

[ (entrynameCb dname3] C . . . ] ) 

names each entry in the catalog recovery area 
that is to be copied to the OUTFILE data set. All 
other entries in the catalog recovery area are 
not copied. 

entryname 

names an object whose catalog entry is 
contained in the dnamel volume's catalog 
recovery area. You can specify the entryname 
of the following entry types: alternate 
index, cluster, and nonVSAM. 

When you specify a cluster entry, the 
cluster's data and index entries and all 
associated path entries are also copied. In 
addition, the cluster's contents (that is, 
its data records, in logical sequential 
order) are copied, following the copies of 
the cluster's catalog entries. 

When you specify an alternate index entry, 
the alternate index's entries and contents 
and all associated path entries are copied 
as though it were a key-sequenced cluster. 

dname3 

identifies the DD statement that describes 
each volume that contains part of the 
cluster or alternate index. dname3 is 
ignored when specified for a nonVSAM entry. 

dname3 is required when the entry is a VSAM 
cluster or alternate index whose data 
resides on volumes other than the volume 
identified with the dnamel DD statement. The 
dname3 DD statement must also include the 
volume referenced by the dnamel DD 
statement. 

Abbreviation: ENT 

NONE 

specifies that no object in the volume's catalog 
recovery area is to be recovered. You must 
specify dnamel NONE for each volume referenced in 
a dname2 or dname3 DD statement if you do not 
wish the entries in its catalog recovery area to 
be recovered. 
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optional Parameters 



FORCE I NOFORCE 

specifies whether the catalog entry's copy is to be copied 
from the catalog recovery area even though the copy itself 
might be inaccurate. 

When you specify FORCE/ EXPORTRA ignores time stamp and 
extent mismatches and the object's catalog-entry copy is 
copied from the volume's catalog recovery area, even though 
a loss of data integrity might result. Otherwise, when the 
catalog recovery area's copy is not accurate, it is not 
copied and the EXPORTRA command terminates with an error 
message. 

Abbreviations: FRC and NFRC 

MASTERPWC password) 

specifies the master catalog's master password. The master 
catalog's master password is required when the master 
catalog is password-protected. 

Abbreviation: MRPW 
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EXPORTRA 
EXPORTRA EXAMPLES 
Using EXPORTRA for All Entries on one volume: Example 1 

This example shows the EXPORTRA function for one volume, VO, 
owned by the VSAM master catalog. All of the entries contained 
in the catalog recovery area on VO and the data sets themselves 
are copied to a SAM data set on another disk volume. All of the 
data sets reside entirely within the one volume. 

//EXPORTRA JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//VLVO DD UNIT=3330,VOL=SER=V0,AMP='AMORG',DISP=OLD 
//VOLOUT DD UNIT=3330,VOL=SER=333003,DSN=OUT.FILE, 
// DISP=(NEU,KEEP),SPACE=(CYL,(5,1)), 
// DCB=BLKSIZE=6000 
//SYSIN DD * 
EXPORTRA - 

OUTFILE(VOLOUT) - 

CRA ( - 

(VLVO ALL)) 
/* 

The job control language statements are' 

• VLVO DD, which identifies and allocates the volume whose 
catalog recovery area contents are to be copied. The data 
sets reside wholly within the one volume. 

• VOLOUT DD, which identifies the sequential file that is to 
receive the copied data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. 

The EXPORTRA command copies everything appearing in the catalog 
recovery area of volume VO. The EXPORTRA command parameters are: 

• OUTFILE, which is required and identifies the sequential 
(SAM) nonVSAM data set that is to receive the copied 

i nf ormat i on. 

• CRA, which is required and identifies the catalog recovery 
area and volume from which the copy is to take place. VLVO 
identifies the DD statement for the catalog recovery volume. 
The ALL subparameter specifies that all entries are to be 
copied from the catalog recovery area. The INFILE 
subparameter is not required because the data sets are 
contained wholly within the one volume. 

Using EXPORTRA for All Entries on Multiple Volumes: Example 2 

This example shows the EXPORTRA function for one volume owned by 
the VSAM master catalog. All data sets contained on the volume, 
VO, and their corresponding CRA entries describing the data sets 
are copied to a sequential (SAM) data set on a tape volume. The 
catalog recovery area contains data sets which reside on volumes 
VI and V2 in addition to the recovery volume, VO. The entries in 
the catalog recovery areas of the additional volumes are not to 
be recovered. 
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//EXPORTRA JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//VLVO DD UNIT=3330,VOL=SER=V0,AMP='AMORG', 
// DISP=OLD 

//VLV1 DD UNIT=3330,VOL=SER=V1,AMP='AMORG', 
// DISP=OLD 

//VLV2 DD UNIT=3330,VOL=SER=V2,AMP='AMORG t , 
// DISP=OLD 

//VOLA DD UNIT=(3330,3),VOL=SER=(VO,V1,V2), 
// AMP= f AMORG',DISP=OLD 

//VOLOUT DD DSN=OUT.FILE,LABEL=(l,SL), 
// DISP=(NEW,KEEP), 

// UNIT=2400-3,VOL=SER=TAPE01, 

// DCB=(BLKSIZE=8192,DEN=3) 

//SYSIN DD * 
EXPORTRA - 

OUTFILE(VOLOUT) - 

CRA ( - 

(VLVO ALL INFILE(VOLA)) - 
CVLV1 NONE) - 
(VLV2 NONE)) - 

MASTERPW(MCATMRPW) 
/x 

The job control language statements are' 

• VLVO DD, which identifies the volume whose catalog recovery 
area contents are to be exported. 

•' VLV1 and VLV2 DD, each of which identifies a volume 

containing part of a multivolume data set but whose catalog 
recovery area contents are not to be exported. 

• VOLA DD, which identifies all the volumes containing the 
data sets to be exported. 

• VOLOUT DD, which identifies the sequential tape file that is 
to receive the exported data sets and catalog recovery 
records. The DCB BLKSIZE parameter overrides the default of 
2048 to improve performance. 

The EXPORTRA command copies every entry appearing in the catalog 
recovery area of volume V0 and the data sets described by the 
CRA entries. Two additional volumes, VI and V2, are referenced 
since they contain part of multivolume data sets, but the 
entries in their catalog recovery areas are not exported. The 
EXPORTRA command parameters are-* . 

• OUTFILE, which is required and identifies the sequential 
(SAM) nonVSAM data set that is to receive the exported 

i nf ormati on. 

• CRA, which is required and identifies the catalog recovery 
area and volumes from which the copy is to take place. VLVO 
identifies the DD statement of the recovery volume. The ALL 
subparameter specifies that all entries in the catalog 
recovery area of the volume identified by VLVO are to be 
copied. The INFILE subparameter is required, since the data 
sets to be copied are contained on multiple volumes. VOLA 
references the DD statement which identifies these multiple 
volumes, including the recovery volume. The VLV1 NONE and 
VLV2 NONE subparameters ar& necessary because the volumes 
they identify are referenced in a previous INFILE 
subparameter; however, the contents of their catalog 
recovery areas are not to be copied. 

• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required when the master catalog 
is password protected. 
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EXPORTRA 

Using EXPORTRA for Selected Entries: Example 3 

This example shows the EXPORTRA function for selected entries 
from the catalog recovery area of one volume owned by the VSAM 
master catalog. Three data sets and their corresponding entries 
from the catalog recovery area on volume VO are copied to a 
sequential (SAM) data set on another disk volume. The remainder 
of the data sets and the catalog recovery area entries are not 
copied. Two of the selected data sets are multi volume VSAM data 
sets. The data sets and their corresponding entries in the 
catalog recovery areas of the additional volumes are not 
recovered. 

//EXPORTRA JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//VLVO DD UNIT=333Q,AMP= f AMORG' ,DISP=0LD, 
// VOL=SER=V0 

//VLV1 DD UNIT=3330,AMP= , AMORG , ,DISP=OLD, 
// V0L=SER=V1 

//VLV2 DD UNIT=3330,AMP='AMORG',DISP=OLD, 
// V0L=SER=V2 

//VOLA DD UNIT=(3330,3),AMP='AMORG' ,DISP=0LD, 
// VOL=SER=(VO,V1,V2) 

//VOLB DD UNIT=(3330,2),AMP='AMORG',DISP=OLD, 
// VOL=SER=(VO,V1) 

//VOLOUT DD UNIT=3330,VOL=SER=333003,DSN=OUT.FILE, 
// DISP= (NEW, KEEP ) , SPACE=(CYL, (5,1)) 

//SYSIN DD * 
EXPORTRA - 

OUTFILE(VOLOUT) - 
CRA ( - 

(VLVO ENTRIES ( - 

(LARGE.DATASET.A VOLA) - 
(LARGE. DATASET.B VOLB) - 
(LARGE. DATASET.C))) - 
(VLV1 NONE) - 
(VLV2 NONE)) - 
FORCE 
/x 

The job control language statements are : 

• VLVO DD, which identifies the volume whose catalog recovery 
area contains the entries for the three VSAM data sets to be 
copi ed. 

• VLV1 and VLV2 DD, each of which identifies a volume 
containing part of a multivolume data set but whose catalog 
recovery area contents are not to be copied. 

• VOLA DD, which identifies the multivolumes of 
LARGE.DATASET.A 

• VOLB DD, which identifies the multivolumes of 
LARGE. DATASET.B 

• VOLOUT DD, which identifies the sequential file that is to 
receive the copied data sets and catalog recoyery records. 

The EXPORTRA command exports the three entries — LARGE.DATASET.A, 
LARGE. DATASET.B, and LARGE. DATASET . C — from the catalog recovery 
area on volume VO. Two additional volumes are referenced, since 
they contain part of multivolume data sets but the entries in 
their catalog recovery areas are not exported. The EXPORTRA 
command parameters are'- 

• OUTFILE, which is required and identifies the nonVSAM data 
set that is to receive the exported information. 

• CRA, which is required and identifies the catalog recovery 
area and volumes from which the export is to take place. 
VLVO identifies the DD statement of the recovery volume. The 
ENTRIES subparameter identifies the three entries which are 

Command Format 299 



to be copied. LARGE. DATASET . A requires the VOLA subparameter 
because the VSAM data set is contained on three volumes. 
Similarly, LARGE. DATASET .B requires the VOLB subparameter. 
However, LARGE. DATASET, C is contained wholly within the 
catalog recovery volume, and, therefore, does not require an 
additional dname3 subparameter. The VLV1 NONE and VLV2 NONE 
subparameters are necessary because the volumes they 
identify are referenced in previous dname3 subparameters 
CVOLA and VOLB); however, the contents of their catalog 
recovery areas are not to be copied. 

FORCE, which specifies that timestamp mismatches are to be 
ignored. 
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IMPORT 



IMPORT 



The format of the IMPORT command, when it is used to connect a 
user catalog* is: 



IMPORT 



CONNECT 

OBJECTSC (usercatname 

DEVICETYPE(devtype) 

VOLUMES(volser))) 

[ CATALOG ( ma st erca t name 1/ pas sword] )3 



The format of the IMPORT command, when it is used to move or 
restore a cluster or alternate index, is : 



IMPORT 



(INFILE( dname ) | INDATASET (entryname )} 
(OUTFILEldnameC/password] ) I 

OUTDATASET( entryname [/password 3 )} 
CERASEIN0ERASE3 
CINT0EMPTY3 
COBJECTS( (entryname 

CFILE(dname)] 

[KEYRANGESUlowkey b highkey) 
[(lowkey b hi ghkey ). . . 3 )3 

CNEUNAME(newname)3 

[ORDERED | UNORDERED 3 

[VOLUMES(volser[b volser. . . 3 )3 ) 
[ ( entryname. ..)... 3 )3 
[PURGEI N0PURGE 3 
[SAVRAC TN0SAVRAC 3 

[CATAL0GCcatname[/password3 )3 



IMPORT may be abbreviated 1 IMP 



IMPORT PARAMETERS 



Required Parameters 



CONNECT 

specifies that the entry to be imported is a user catalog. 
The user catalog is connected to the master catalog in the 
receiving system. If CONNECT is coded, OBJECTS must also be 
coded to name the catalog and to identify the volume serial 
number and device type of the volume that contains the user 
catalog. 

Abbreviation: CON 

INFILE(dname) 

specifies the name of a DD statement that identifies the 
portable copy of the cluster or alternate index to be 
imported. If a non-labeled tape or a direct-access data set 
created by DOS/VS Access Method Services contains the copy, 
the following DCB parameters must be specified on the 
referenced DD statement^ 

• BLKSIZE. If you specified BLKSIZE when the cluster or 
alternate index was exported, you must specify the same 
blocksize value for IMPORT. (Note: If you did not 
specify a blocksize for EXPORT, a default value of 2048 
was used. Consequently, if you do not specify BLKSIZE 
for IMPORT, IMPORT sets the blocksize to 2048.) 

• LRECL. LRECL is based on the maximum record size of the 
exported VSAM data set. Maximum record size is 
determined by the value specified via the maximum 
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subparameter of the RECORDSIZE parameter of the DEFINE 
CLUSTER or DEFINE ALTERNATEINDEX command when the data 
set was defined. If the portable data set was created 
on a system with the 0S/VS2 MVS Supervisor Performance 
82 Selectable Unit VS2. 03.807, LRECL is as follows: 

For relative record data sets, the greater of 276, 
or maximum VSAM logical record size plus 8 

For all other types of VSAM data sets, the greater 
of 272, or maximum VSAM logical record size plus 4 

• If the portable data set was created on any system 
without VS2.03.807, 

For relative record data sets, the greater of 268, 
or VSAM logical record length plus 8 

For all other types of VSAM data se.ts, the greater 
of 264, or maximum VSAM logical record length plus 

(Note: If you do not specify LRECL, IMPORT uses a 
default value of BLKSIZE - 4.) 

• RECFM. Must be VBS. 

Abbreviation: IFILE 

INDATASETC entryname) 

names the cluster or alternate index to be imported. 

If INDATASET is specified, the entryname is dynamically 
allocated. The entryname must be cataloged in a catalog 
that is accessible by the system into which the entry is to 
be imported. The characteristics of the input data set are 
described under the INFILE parameter. 

Abbreviation: IDS 

OUTFILECdnameC/password] ) 

specifies the name of a DD statement that identifies the 
data set name and volume(s) that is to receive the cluster 
or alternate index that is to be imported. If the data set 
was permanently exported and/or you are importing to a 
volume other than the original volume, the DD statement 
specifies the name of the cluster or alternate index as 
DSNAME, the volume serial number(s), the device type, 
DISP=0LD, and AMP='AM0RG'. In addition, you must use 
concatenated DD statements when both of the following 
conditions exist and the data set was permanently exported : 

• An alternate index or key-sequenced cluster is being 
imported. 

• Its data and index components are on different device 
types. 

The first DD statement specifies the name of the cluster or 
alternate index as the DSNAME, the volume serial numbers 
and device type of the data component, DISP=0LD, and 
AMP='AM0RG'. The second DD statement specifies the name of 
the index component as the DSNAME, the volume serial 
numbers and device type of its index component, DISP=0LD, 
and. AMP='AM0RG» . 

If NEWNAME is specified for the cluster or alternate index 
entry, the data-set name on the DD statement must- be the 
same as the new name. The volume that is to receive the 
imported cluster or alternate index must be owned by a VSAM 
catalog. 
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password 

is the update (or highei — level) password of the output 
cluster or alternate index. You must supply the 
password when the output data set is empty (see the 
VOLUMES parameter for more information about importing 
into an empty data set). Otherwise* IMPORT obtains the 
required VSAM data set passwords from the portable 
data set. 

When you use a DD statement to describe the output data 
set* you must identify the data set's catalog with a JOBCAT 
or STEPCAT DD statement unless: 

♦ The data set's entry is in the master catalog* or 

• The first qualifier of the data set's qualified name 
identifies a catalog (that is* the first qualifier is 
the catalog's name or alias). 

Note : When importing a cluster that was permanently 
exported* the OUTFILE parameter should be used. 

Abbreviation: OFILE 

OUTDATASETCentrynameC/ password] ) 

specifies the name of the data set that is to receive the 
data being imported. When you specify OUTDATASET* the VSAM 
data set you identify is dynamically allocated. If NEWNAME 
is specified for the cluster or alternate index entry* 
entryname must be the same as the new name. 

password 

is the update- (or highei — level) password of the 
output object. See password under INFILE for password 
requirements of the output data set. 

Abbreviation: ODS 



Optional Parameters 



CATALOGtcatnameC/password] ) 

specifies the name of the catalog in which the imported 
object is to be cataloged. This parameter is required when 
the catalog is password protected. 

catname 

is the name of the catalog in which the entry to be 
imported is to be defined. If you are importing a user 
catalog* the specified catalog must be the master 
catalog. 

password 

specifies the catalog's update or higher level 
password. When you import an alternate index whose 
base cluster is password-protected* you should supply 
the catalog's master password. Otherwise* you (or the 
operator) will be prompted to supply the base 
cluster's master password. 

Abbreviation: CAT 

ERASE |NOERASE 

specifies whether the data component of the cluster or 
alternate index that was exported with the TEMPORARY option 
is to be erased (that is* overwritten with binary zeros). 
This parameter can be used only when you are importing the 
object into the system from which it was previously 
exported with the TEMPORARY option. This parameter 
overrides whatever was specified when the object was 
defined or last altered. 

Abbreviations: ERAS and NERAS 
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INTOEMPTY 

specifies that you are importing into an empty data set. If 
this parameter is not specified, an attempt to import into 
an empty data set will fail. Importing into an empty data 
set causes the data set to be loaded from the portable data 
set. The password and RACF profiles associated with the 
empty data set will be retained. When importing into an 
empty data set, the SAVRAC I NOSAVRAC parameter applies 
only to the paths imported and successfully defined over 
the empty data set. If the define of an exported path fails 
because a catalog entry with the same name already exists, 
the path on the portable data set is ignored. 

Abbreviation: IEMPTY 

OBJECTS 

specifies the new or changed attributes for the cluster, 
alternate index, any associated paths, or user catalog to 
be imported. 

By specifying the OBJECTS parameter i 

• You provide the information needed to connect a user 
catalog to the master catalog, or 

• You may override certain attributes of the cluster or 
alternate index (and associated paths) to be imported 
in order to provide new or changed attributes. Access 
Method Services matches each entryname you specify 
through the OBJECTS parameter against the name of each 
object on the portable data set. When a match is found, 
the information specified by OBJECTS overrides the 
information on the portable data set. The description 
for each of the OBJECTS subparameter includes 
information on how they should be specified; that is, 
what name you should specify as the entryname to 
accomplish the results you want. 

You can specify OBJECTS 

• For a user catalog 1 

OBJECTS ( (usercatname 

DEVICETYPECdevtype) 

VOLUMES(volser))) 

• For a cluster, alternate index, or path** 

OBJECTS ( (entryname 

CFILE(dname)] 

EKEYRANGESUlowkey b highkey) 
[(lowkey b highkey)...])] 

ENEWNAME(newname)] 

[ORDERED | UNORDERED] 

[ VOLUMES (volserEb volser...])] 

[(entryname...)...]) 

usercatname 

specifies the name of the user catalog being 
connected. 

entryname 

specifies the name of the data component, index 
component* cluster, alternate index, or path for which 
attributes are being specified. For a cluster, 
alternate index, data component, index component, or 
path, this name must appear on the oortable data set; 
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otherwise* the parameter list will be ignored. 

Abbreviation: OBJ 

DEVICETYPE(devtype) 

specifies the device type of the volume that contains 
a user catalog that is to be connected. You can 
specify a device type for any direct-access device 
that is supported by your 0S/VS2 MVS system. 

Abbreviation: DEVT 

FILE(dname) 

specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key-sequenced cluster or of an alternate index. 
This parameter is required when the components are 
defined as unique and when the data and index 
components reside on different device types. When 
components reside on different device types* FILE must 
be coded twice within the OBJECTS parameter 1 once in 
the parameter set for the index component and once in 
a second parameter set for the data component. If you 
do not specify FILE* the required volumes are 
dynamically allocated. 

KEYRANGES (Uowkey b hi ghkey ) C ( lowkey b hi ghkey ) . . . 3 ) 
specifies portions of a key-sequenced cluster or 
alternate index to be placed on separate volumes. 

The data is divided, by key* among the volumes as 
contained in the portable data set or as specified in 
the VOLUMES parameter. If a volume serial number is 
duplicated on the portable data set or in VOLUMES* 
multiple key ranges of an alternate index or cluster 
attribute are placed on that volume. If the number of 
volumes is greater than the number of key ranges, the 
excess volumes are used for overflow records from any 
key range without consideration of range boundaries. 
If there are fewer volumes than key ranges* the excess 
key ranges are placed on the last volume specified. 

By using the KEYRANGE parameter you may specify key 
range pairs for a key-sequenced data set that 
previously was not divided by key or that was divided 
in different key range groups. 

The maximum number of key-range pairs is 20. Key 
ranges must be in ascending order* and may not 
overlap. Gaps may exist within a specified set of 
ranges, but records cannot be inserted within a gap. 

When you specify KEYRANGES* entryname can be either 
the cluster or alternate index name or the name of the 
data component. If you specify KEYRANGES with the 
cluster or alternate index name* the values specified 
are propagated to and defined for the data component. 
If you specify KEYRANGES with the data component name 
the values are defined for the data component and any 
specification of KEYRANGES with the cluster or 
alternate index name is overridden. 

Keys can contain 1 to 64 characters; if coded in 
hexadecimal, they may contain 1 to 128 hexadecimal 
characters. All EBCDIC characters are allowed. Keys 
consisting of characters must be enclosed in single 
quotation marks if they contain commas, semicolons, 
blanks, parentheses, or slashes. A single quotation 
mark within a key must be coded as two single 
quotation marks if the key is enclosed in single 
quotation marks. If the key is specified in 
hexadecimal, it must be preceded by X and be enclosed 
in single quotation marks. 
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lowkey 

specifies the low key of the key range. If lowkey 
is shorter than the actual keys, it will be 
padded with binary zeros. 

highkey 

specifies the high key of the key range. If 
highkey is shorter than the actual keys, it will 
be padded with binary ones. 

Abbreviation: KRNG 

NE14NAME ( n ewname ) 

specifies the new name of an imported cluster or 
alternate index or its components, or an associated 
path. When you specify NEWNAME, only the name 
specified as entryname is changed. You cannot specify 
NEWNAME if entryname identifies a user catalog. 

The new name can contain 1 to 44 alphameric characters 
(A through Z, and through 9), national characters 
(3), #, and $), and special characters (the hyphen and 
12-0 overpunch) . Names that contain more than eight 
characters must be segmented by periods; one to eight 
characters may be specified between periods. The first 
character of the name or name segment must be either 
an alphabetic character or a national character. If 
you specify the new name in the format 
newnameCmodi f i er) , only that portion of the name 
preceding the left parenthesis will be used*. The 
modifier enclosed in parentheses will be ignored. 

If you are specifying a new name for a cluster or 
alternate index that was exported with the TEMPORARY 
option and it is being imported back into the original 
system, you must rename each of its components, also. 

Abbreviation: NEWNM 

ORDERED | UNORDERED 

specifies whether volumes are to be used in the order 
in which they were listed when the data set was 
originally defined (as contained on the portable data 
set) or in the VOLUMES parameter. If the data set is 
divided into key ranges, all of the records within the 
range specified by the first low-key/high-key pair are 
placed on the first volume; all of the records within 
the second range &r& placed on the second volume; etc. 
If it is impossible to allocate volumes in the given 
order and ORDERED is specified, the command is 
termi nated. 

When you specify ORDERED I UNORDERED, you can specify 
the cluster or alternate index name, the data 
component name or the i ndex component name as 
entryname with the following results* 

• If ORDEREDlUNORDERED is specified with the cluster 
or alternate index name, the specified attribute 

i s propagated to and defined for the data and, for 
a key-sequenced cluster or alternate index, the 
index component. 

• If ORDEREDlUNORDERED is specified with the data 
component name, the specified attribute is defined 
for the data component. Any specification of 
ORDEREDlUNORDERED with the cluster or alternate 
index name is overridden. 

• For a key-sequenced cluster and for an alternate 
index, if ORDEREDlUNORDERED is specified with the 
index component name, the specified attribute is 
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defined for the index component. Any specification 
of ORDEREDlUNORDERED with the cluster or alternate 
index name is overridden. 

Abbreviations: ORD and UNORD 

VOLUMES(volserCb volser.,.3) 

specifies the volumes on which the cluster or 
alternate index is to reside or the volume on which 
the user catalog resides. 

The volume serial number may contain one to six 
alphameric, national (3), #, and $), hyphens, and 
special (commas, semicolons, blanks, parentheses, 
slashes, asterisks, periods, quotation marks, 
ampersands, plus signs, and equal signs) characters. 
The volume serial numbers must be enclosed in single 
quotation marks if they contain special characters. 
Single quotation marks within a volume serial number 
must be coded as two single quotation marks. 

If VOLUMES is not coded, the original volume is the 
receiving volume. This parameter is required when a 
user catalog is to be imported; when importing a user 
catalog, specify only one volume. If the portable data 
set was created with an EXPORT command using the 
PERMANENT "opti on on a Release 1 version of Access 
Method Services (DOS/VS Release 29, 0S/VS1 Release 2, 
0S/VS2 Release 1.6, or 0S/VS2 Release 2), this 
parameter is required. Portable data sets created by 
Release 1 using the PERMANENT option do hot contain 
volume information. 

When you specify VOLUMES, you can specify the cluster 
or alternate index name, the data component name or 
the index component name as entryname with the 
following results: 

• If VOLUMES is specified with the cluster or 
alternate index name, the specified volume list is 
propagated to and defined for the data and, for a 
key-sequenced cluster or alternate index, the 
index component. 

• If VOLUMES is specified with the data component 
name, the specified volume list is defined for the 
data component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 

• For a key-sequenced cluster or alternate index, if 
VOLUMES is specified with the index component 
name, the specified volume list is defined for the 
index component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 

For clusters or alternate indexes, multiple volumes, 
if specified, must be of the same device type. By 
repeating the OBJECTS parameter set for each component 
and including VOLUMES in each parameter set, you can 
have the data and index components on different 
volumes. Although the index and data components may 
reside on different device types, each volume of a 
multivolume component must be of the same type. 

If the receiving volume i s of a type different from 
that that originally contained the cluster or 
alternate index, the job may be terminated because of 
allocation problems. Each space allocation quantity is 
recorded in a catalog entry as an amount of cylinders 
or tracks even when RECORDS was specified in the 
DEFINE command. When a cluster or alternate index is 
imported, the number of cylinders or tracks in the 
catalog entry is not modified, even though the object 
may be imported to reside on a device type other than 
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that it was exported from. An attempt to import an 
object that previously resided on a 3330 may fail if 
it is imported to a 2314. Conversely, if an object is 
exported from a 2314 and imported to a 3330/ more 
space is allocated than the object needs. 

You can avoid space allocation problems when, you 
define an empty cluster or alternate index on the new 
system or catalog and identify it as the target for 
the object being imported as described below: 

• Using the DEFINE command, define a new entry for 
the cluster or alternate index in the catalog to 
which it is to be moved. If space was allocated in 
RECORDS, you may specify the same quantity; if it 
was allocated in TRACKS or CYLINDERS, you must 
adjust the quantity for the new device type. If an 
entry already exists in the catalog for the 
object, you must delete that entry qr use a 
different name in the DEFINE command. 

• Using the IMPORT command, load the portable data 
set into the newly defined cluster or alternate 
index. When IMPORT encounters an empty target data 
set, the exported catalog information is bypassed 
and just the data records are processed. 

Abbreviation: VOL 

PURGEl NOPURGE 

specifies whether the original cluster or alternate index 
is to be deleted and replaced regardless of the retention 
time specified in the TO or FOR parameter. This parameter 
can be used only when you are importing the - object into the 
original system from which it was exported with the 
TEMPORARY option. 

Abbreviations: PRG and NPRG 

SAVRAC I NOSAVRAC 

specifies, for a RACF-protected object, whether existing 
profiles are to be used or whether new profiles ar& to be 
created. 

SAVRAC should be specified when RACF data set profiles 
already exist for objects being imported from the portable 
data set. Typically, you would specify this option when 
replacing a data set with a portable copy made with an 
EXPORT TEMPORARY operation. SAVRAC will cause the existing 
profiles to be "saved" and used, rather than letting the 
system delete old profiles and create new, default 
profiles. 

Caution : You should ensure that valid profiles do exist for 
all components (for example, cluster, data, index) being 
imported when SAVRAC is specified. If this is not done, an 
invalid and possibly improper profile may be "saved" and 
used inappropriately. Remember, that paths ar& imported 
along with their corresponding cluster or alternate index, 
and the same caution applies to these entries. In 
particular, keep in mind that additional paths may be 
brought in during the import. 

NOSAVRAC should be specified when you wish new profiles to 
be created. This is usually the situation when importing a 
permanently exported cluster or alternate index. A profile 
will be defined for the imported components if either the 
Automatic Data Set Protection option has been specified for 
you or if the exported component had a RACF indication in 
the catalog when it was exported. If you import into a 
catalog in which there is a component with a duplicate name 
which is marked as having been temporarily exported, it and 
any associated profiles will be deleted before importing 
the portable data set. 
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IMPORT EXAMPLES 

importing a User Catalog: Example 1 

In this example, a user catalog, D27UCAT1, is imported and 
connected to the new system's master catalog, AMASTCAT. This 
example reconnects the user catalog, D27UCAT1, that was 
disconnected with EXPORT Example 3. 

//IMP0RT1 JOB . . . 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
IMPORT - 

OBJECTSC - 

(D27UCAT1 - 
VOLUMECVSER02) - 
DEVICETYPE(2314) ) - 
) - 
CONNECT - 

CATAL0G(AMASTCAT/MRCATPW2) 
/K 

The job control language statement is* 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The IMPORT command builds a user catalog connector entry that 
identifies the user catalog D27UCAT1 in the master catalog 
AMASTCAT. Its parameters are : 

• OBJECTS, which is required when a user catalog is being 
imported. The subparameters of OBJECTS identify the user 
catalog, D27UCAT1, the user catalog's volume, VSER02, and 
the device type of the user catalog's volume, 2314. 

• CONNECT, which specifies that the user catalog connector 
entry is to be built and put in the master catalog to 
connect the user catalog to the master catalog. CONNECT is 
required when a user catalog is being imported. 

• CATALOG, which identifies the master catalog, AMASTCAT, and 
specifies its update- (or highei — level) password, MRCATPW2. 

importing a Key-Sequenced Cluster: Example 2 

In this example, a key-sequenced cluster, D40 . EXAMPLE. KSDS1 , 
that was previously exported, is imported. (See the EXPORT 
example, "Exporting a Key-Sequenced Cluster.") OUTFILE and its 
associated DD statement are provided to allocate the data set. 

The original copy of D40 . EXAMPLE. KSDS1 is replaced with the 
imported copy, TAPE2. Access Method Services finds and deletes 
the duplicate name, D40 . EXAMPLE. KSDS1 , in the catalog D27UCAT1. 
(A duplicate name exists because TEMPORARY was specified when 
the cluster was exported.) Access Method Services then redefines 
D40 . EXAMPLE. KSDS1 using the catalog information from the 
portable file, TAPE2. 
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//IMP0RT2 JOB 
//STEP1 EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPE2,UNIT=(2400-3,, DEFER), 
// VOL=SER=003030,DISP=OLD, 

// DCB=(BLKSIZE=6000,LRECL=479,DEN=3),LABEL=C1,SL) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
IMPORT - 

INFILE(SOURCE) - 

OUTDATASETCD40. EXAMPLE. KSDS1) - 

CATALOG (D27UCAT1/MRPWD27) 
/* 

The job control language statements are: 

• SOURCE DD, which describes the portable data set, TAPE2. 
TAPE2 resides on a magnetic tape file, which will not be 
mounted by the operator until Access Method Services opens 
TAPE2 for processing. The blocksize parameter is included 
(even though it need not be, because the tape has a standard 
label and the information is contained in the data-set 
header label) to illustrate the fact that the information 
specified when the data set i s imported is required to be 
the same as was specified when the data set was exported. 
The LRECL parameter is not required, because the maximum 
record size is 475 bytes and the default (blocksize minus 4) 
is adequate. However, by specifying a recordsize, the 
default is overridden and virtual storage is more 
efficiently used. When recordsize is specified, it is the 
largest-record size + 4. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer arts to be sent. 

The IMPORT command copies the portable data set, TAPE2, into the 
system and assigns it the name D40 . EXAMPLE. KSDS1 . When TAPE2 is 
copied, Access Method Services reorganizes the data records so 
that deleted records are removed and control intervals and 
control areas contain the specified freespace percentages. The 
original copy of the cluster is deleted and replaced with the 
data records from the TAPE2 portable file. The IMPORT command's 
parameters are: 

• INFILE, which points to the SOURCE DD statement. The SOURCE 
DD statement describes the portable file, TAPE2, to be 
imported. 

• OUTDATASET, which gives the name of the data set being 
imported. Since the high-level qualifier of the data set is 
the name of the alias of the user catalog D27UCAT2, Access 
Method Services can dynamically allocate the cluster without 
specifying a JOBCAT or STEPCAT DD statement. 

• CATALOG, which identifies the catalog, D27UCAT1, in which 
the imported cluster is to be defined. The catalog's update- 
(or highei — level) password is required. 

Importing an Entry-Sequenced VSAtl Cluster: Example 3 

In this example, an entry-sequenced cluster, D50 . EXAMPLE. ESDS1 , 
is imported from a portable file, TAPE1. This example is 
associated with EXPORT Example 2, "Exporting an Entry-Sequenced 
Cluster." The cluster is defined in a different catalog from 
which it was exported, assigned a new name, and imported to a 
different volume. 
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//IMP0RT3 JOB ... 
//STEP1 EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPEl,UNIT=(2400-3,, DEFER), DISP=OLD, 
// VOL=SER=001147,LABEL=C1,SL) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
IMPORT - 

INFILE(SOURCE) - 
OUTDATASETCD40. EXAMPLE. ESDS3) - 
OBJECTSC - 

(D50. EXAMPLE. ESDS1 - 

NEWNAMECD40. EXAMPLE. ESDS3) - 
VOLUMESCVSER02) ) - 
) - 
CATAL0GCD27UCAT1/UPPWD27) • 
/x 

The job control language statements are : 

• SOURCE DD, which describes the portable file, TAPE1. TAPE1 
resides on a magnetic tape file, which will not be mounted 
by the operator until Access Method Services opens TAPE1 for 
processi ng. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The IMPORT command moves the contents of the portable file, 
TAPE1, into the system. When TAPE1 is moved, Access Method 
Services reorganizes the data records. The IMPORT command's 
parameters are- 

• INFILE, which points to the SOURCE DD statement. The SOURCE 
DD statement describes the data set to be imported, TAPE1. 

• OUTDATASET gives the name of the data set that is being 
imported — the name is the renamed cluster. Since the 
high-level qualifier of the data set name is the name of the 
alias of the catalog, D27UCAT1, the data set can be 
dynamically allocated without specifying a JOBCAT or STEPCAT 
DD statement. 

• OBJECTS, which changes some of the attributes for the object 
being imported 1 

D50 . EXAMPLE. ESDS1 , which identifies the entry-sequenced 
cluster as it is currently named on TAPE1. 

NEWNAME, which specifies that the cluster's entryname is 
to be changed to D40 . EXAMPLE. ESDS3 . 

VOLUMES, which identifies the new volume on which the 
cluster is to reside. 

• CATALOG, which identifies the catalog, D27UCAT1, that is to 
contain the cluster's catalog entry. The catalog's update- 
(or highei — level) password is required. 
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The format of the IMPORTRA command is- 



IMPORTRA 



{INFILE(dname)|INDATASET(entryname)} 
COUTFILE(dname)] 
[OBJECTSC 
(entryname 

[DEVICETYPES(devtype£b devtype. . 
[FILE(dname)3 

[VOLUMEStvolserCb volser. . . ] ) ] ) 
C (entryname. ..)...])] 
[SAVRAC1 N0SAVRAC 3 

[CATALOG(catname[/password] )] 



])3 



IMPORTRA can be abbreviated: MPRA 



IMPORTRA PARAMETERS 



Required Parameters 
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Abbreviation: IFILE 



INDAT ASET t ent ryname ) 

specifies the data set name of the portable data set. When 
you specify INDATASET instead of INFILE, the portable data 
set (that is, the data set that resulted when you issued 
the EXPORTRA command) is dynamically allocated. 



Abbreviation: IDS 



Optional Parameters 



CATALOGt catnameC/password] ) 

identifies the target catalog (that is, the catalog that is 
to contain the imported catalog entries). 

If you do not include the CATALOG parameter, the JOBCAT or 
STEPCAT catalogs are used. If you have not specified a 
JOBCAT or STEPCAT catalog, the VSAM master catalog is used. 
You must specify the CATALOG parameter when the target 
catalog is password protected. Otherwise, the system 
operator is prompted to supply the correct password. 

catname 

names the catalog. When you specify a user catalog, 
you must describe and allocate the catalog with a 
JOBCAT or STEPCAT DD statement. 
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password 

is the target catalog's update- or highei — level 
password, if the catalog is password protected. If any 
of the data sets being imported is an alternate index 
whose base cluster is password protected, you should 
supply the catalog's master password. 

Abbreviation: CAT 

OBJECTSC (entryname 

CDEVICETYPES(devtype[b devtype. . . ] )] 
CFILE(dname)] 

CVOLUMESCvolserCb volser. ..])]) 
C (entryname. ..)...]) 

The OBJECTS parameter group specifies new or changed 
attributes for objects on the portable data set. 

Attributes may be specified for a cluster, alternate index, 
user catalog, or nonVSAM data set. By specifying the 
OBJECTS parameter, you may override certain attributes 
contained on the portable data set. Access Method Services 
matches each entryname you specify against the name of each 
object on the portable data set. When a match is found, the 
information specified by OBJECTS overrides the information 
on the portable data set. 

entryname 

specifies the object's entryname. You can specify the 
entryname and associated attributes for up to 255 
objects. 

You can specify the entryname of these types of 

objects only : VSAM cluster or alternate index, nonVSAM 

data set, user catalog, and a VSAM object's data or 
index component. 

Abbreviation: OBJ 

DEVICETYPESCdevtypeEb devtype. . . 3 ) 

specifies the device type on which a user catalog 
being imported resides or the device type(s) on which 
a nonVSAM data set being imported resides. If 
entryname names a user catalog, you may specify only 
one device type. If entryname names a nonVSAM data set 
which resides on different device types, the device 
types listed in the DEVICETYPES parameter must be 
specified in the same order as the volume serial 
numbers listed in the VOLUMES parameter. 

This parameter can be specified only when the 
entryname names a nonVSAM data set or user catalog. 
For a nonVSAM data set or user catalog, if DEVICETYPES 
is not coded, the data set or user catalog must still 
reside on the same device type(s) as contained in the 
entry in the portable data set. 

Abbreviation: DEVT 

FILE(dname) 

specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key-sequenced cluster or of an alternate index. 
This parameter is required when the components sr& 
defined as unique and when the data and index 
components reside on different device types. When 
components reside on different device types, FILE must 
be coded twice within the OBJECTS parameter; once in 
the parameter set for the index component and once in 
a second parameter set for the data component, if you 
do not specify FILE, the required volumes are 
dynamically allocated. 
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VOLUMES(volserCb volser...]) 

specifies the volumeCs) on which a cluster or 
alternate index is to reside* the volume on which a 
user catalog resides, or the volumeCs) on which a 
nonVSAM data set resides. If entryname names a user 
catalog* you may specify only one volume serial number 
as a subparameter of VOLUMES. 

For a cluster or alternate index, if VOLUMES is not 
coded, the original volume is the receiving volume. 
For a user catalog or nonVSAM data set, if VOLUMES is 
not coded, the data set or user catalog must still 
reside on the same volumeCs) as contained in the 
portable data set. 



volser 

i s a 1 to 6 alphameric or special character 
volume serial number. 



If the password contains a lowercase alphabetic 
character, it will be folded to an uppercase 
alphabetic character. 



When the volser contains a special character 
Cthat is, a comma E,3, semicolon C;3, blank Cb], 
period C.3, single quote t'3, ampersand [&], plus 
sign [+], equal sign C=3, hyphen C-3, parenthesis 
EC or )3, slash C/3, or asterisk t*3), enclose 
the volser in single-quotation marks Cfor 
example, VOLUMESC » *D0RIS * ) ) . 

When the volser contains a special character and 
also contains a single-quotation mark, code the 
imbedded quotation mark as two single-quotation 
marks Cfor example, VOLUMESC ' *CA' f R0 ')) . 



You can code volser in hexadecimal form, where 
two hexadecimal characters represent one 
alphameric or special character. For example, 
V0LUMESCX'E2E4C5») is the same as VOLUMESCSUE) 



When you specify VOLUMES for a cluster or ♦ 
alternate index, you can specify the cluster or 
alternate index name, the data component name or 
the index component name as entryname with the 
following results : 

• If VOLUMES is specified with the cluster or 
alternate index, name, the specified volume 
list is propagated to and defined for the 
data and, for a key-sequenced cluster or 
alternate index, the index component. 

• If VOLUMES is specified with the data 

' component name, the specified volume list is 
defined for the data component. Any 
specification of VOLUMES with the cluster or 
alternate index name is overridden. 

• For a key-sequenced cluster or alternate 
index, if VOLUMES is specified with the index 
component name, the specified volume list is 
defined for the index component. Any 
specification of VOLUMES with the cluster or 
alternate index name is overridden. 

For cluster or alternate indexes, if multiple 
volumes are specified, they must be of the same 
device type. By repeating the OBJECTS parameter 
set for each component and including VOLUMES in 
each parameter set, you can have the data and 
index components on different volumes. CSee also 
the description of the FILE parameter.) Although 
the index and data components may reside on 
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different device types* each volume of a 

multi volume component must be of the same type. 

Abbreviation: VOL 

OUTFILE(dname) 

names the DD statement that contains a data set name and 
the volume serial number of each volume that is to contain 
the imported VSAM clusters and alternate indexes. You must 
use concatenated DD statements if the data sets are on 
different device types. If the OUTFILE parameter is not 
supplied* the required data sets are dynamically allocated 
as needed. 

The dsname specified with the DD statement cannot be one of 
the names cataloged in the target catalog (that is* the 
catalog that is to contain the imported catalog entries) 
and it cannot be one of the entrynames within the portable 
data set. The section "Restoring the Catalog Entry that was 
Obtained Using the EXPORTRA Command" describes how this 
dsname is used by IMPORTRA processing. The DD statement(s) 
also specify the volume serial number(s)* device type* 
DISP=0LD, and AMP='AM0RG'. 

Abbreviation: OFILE 

SAVRACl NOSAVRAC 

specifies* for a RACF-protected object* whether existing 
profiles are to be used or whether new profiles are to be 
created. 

SAVRAC should be specified when RACF data set profiles 
already exist for objects being imported from the portable 
data set. SAVRAC will cause the existing profiles to be 
"saved" and used* rather than letting the system delete old 
profiles and create new default profiles. 

Caution: You should ensure that valid profiles do exist 
for all components (for example* cluster* data* index) 
being imported when SAVRAC is specified. If this is not 
done* an invalid and possibly improper profile may be 
"saved" and used inappropriately. Remember* that paths are 
imported along with their corresponding cluster or 
alternate index* and the same caution applies to these 
entries. In particular* keep in mind that additional paths 
may be brought in during the import. 

NOSAVRAC should be specified when you wish new profiles to 
be created. A profile will be defined for the imported 
components if either the RACF Automatic Data Set Protection 
option has been specified for you or if the exported 
component had a RACF indication in the catalog at the time 
it was exported. The mode* SAVRAC or NOSAVRAC* set by these 
keywords applies to all VSAM components being imported back 
into the system. 

There may be situations where the SAVRAC or NOSAVRAC mode 
would not be suitable for all entities restored from the 
catalog recovery area. In such cases* the following 
procedure is suggested** 

• Issue two separate EXPORTRA commands* resulting in two 
portable data sets. One EXPORTRA will create a portable 
data set containing entities to which SAVRAC should 
apply* the other to which NOSAVRAC should apply. 

• Issue two IMPORTRA commands* one specifying SAVRAC and 
the other NOSAVRAC. 
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This example shows how EXPORTRA and IMPORTRA can be used to 
recover a VSAM catalog. The first part illustrates the use of 
EXPORTRA. The second part shows how IMPORTRA is used. 

Recovering a VSAM Catalog: Example 1— -Part 1 (EXPORTRA) 

This example performs the EXPORTRA function against the VSAM 
master catalog, AMASTCAT, and against all of the volumes owned 
by it. All of the data sets listed in the catalog recovery areas 
on the catalog volume and on the other volumes owned by AMASTCAT 
&re exported to a SAM data set on another disk volume. Using the 
FORCE option causes EXPORTRA to ignore time stamp mismatches 
between the volumes and the catalog. 

//RECOVER JOB 

//STEP1 EXEC PGM-IDCAMS 

//SYSPRINT DD SYSOUT=A 

//CRAV0L1 DD DISP=OLD,VOL=SER=VSER01,UNIT=2314, 

// AMP='AM0RG' 

//CRAV0L2 DD DISP=0LD, VOL=SER=VSER04,UNIT=3330 , 

// AMP='AM0RG' 

//PORT DD DSNAME=PORT,DISP=(NEW,KEEP), 

// SPACE=CCYL,(3,3)),VOL=SER=231401, 

// UNIT=2314,DCB=BLKSIZE=8000 

//SYSIN DD * 

EXPORTRA - 
CRA( - 

(CRAV0L1 ALL) - 
(CRAV0L2 ALL) - 
) - 
FORCE - 

OUTFILE(PORT) - 
MASTERPW(MCATMRPW) 
/* 

The job control language statements are* 

• CRAV0L1 DD, which identifies and allocates the first volume 
whose catalog recovery area contents is to be exported. 

• CRAV0L2 DD, which identifies and allocates the second volume 
whose catalog recovery area contents is to be exported. 

• PORT DD, which identifies the sequential file that is to 
receive the exported data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. 

The EXPORTRA command exports everything appearing in the catalog 
recovery areas of volumes VSER01 and VSER04. The EXPORTRA 
command T s parameters are* 

• CRA, which is required and identifies the catalog recovery 
areas and volumes from which the export is to take place. 
The dnames of the DD statements for these objects must be 
identical to the names specified for this parameter. The ALL 
subparameter specifies that everything is to be exported 
from each catalog recovery area. 

• FORCE, which specifies that timestamp mismatches are to be 
i gnored. 

• OUTFILE, which is required and identifies the sequential 
(SAM) nonVSAM data set that is to receive the exported 
information. The dname of the DD statement for this object 
must be identical to the name specified with this parameter. 
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• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to export 
information from catalog recovery areas controlled by a 
recoverable catalog. 

Recovering a VSAM Catalog: Example 1 — Part 2 (IMPORTRA) 

This example imports all of the data sets that were exported 
using EXPORTRA in the previous example. The receiving catalog is 
the VSAM master catalog, and the CATALOG parameter is used to 
supply its master password. 

//RESTORE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//PORT DD DSNAME=P0RT,DISP=0LD,UNIT=2314, 

// VOL=SER=231401,DCB=BLKSIZE=80 

//VSAMIN DD DSNAME=DUMMY.NAME,DISP=0LD,UNIT=2314, 

// VOL=SER=VSER01,AMP='AMORG» 

// DD VOL=SER=VSER04,UNIT=3330,DISP=OLD 

//SYSIN DD * 

IMPORTRA - 

INFILE(PORT) - 
OUTFILE(VSAMIN) '- 
CATALOGCAMASTCAT/MCATMRPW) 
/* 

The job control language statements are- 

• PORT DD, which identifies and allocates the portable data 
set created previously by EXPORTRA. The DCB BLKSIZE 
parameter is included (even though it need not be because 
the information is contained in the DSCB for the data set) 
to illustrate the fact that the blocksize specified in the 
IMPORTRA job must be the same as that specified in the 
EXPORTRA. job which created the portable data set. 

• VSAMIN DD, which identifies and allocates the volumes of the 
objects to be imported. This permits them to be reloaded 
from the portable data set. The dsname appearing on the DD 
statement is required. It i s a dummy name that must not 
appear either in the catalog or among the names on the 
portable data set. Because the volumes are of different 
device types, concatenated DD statements must be used. 

The IMPORTRA command imports the data sets written on the 
portable data set by EXPORTRA previously. The IMPORTRA command's 
parameters are'- 

• INFILE, which is required and which identifies the portable 
data set. 

• OUTFILE, which identifies each VSAM volume involved in the 
import. The DD statement identified by OUTFILE also 
identifies the dummy data set, DUMMY. NAME. 

• CATALOG, which specifies the name of the master catalog. The 
master password of the target catalog is required in order 
to import catalog information. 
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The format of the LISTCAT command is* 



LISTCAT 



CCATALOG(catnameC/pas5word3 )] 
[ENTRIES (en try name [/password 3 
[b entryname[/password] . » . ] ) 
LEVEL(level)] 
[ALIAS] 

[b ALTERNATEINDEX3 

CLUSTER] 

DATA] 

GENERATI0NDATAGR0UP3 

INDEX] 

NONVSAM] 

PAGESPACE3 

PATH] 

SPACE] 

USERCATALOG] 



Cb 

Cb 

[b 

Cb 

Cb 

Cb 

Cb 

Cb 

Cb 
CALLl 

ALLOCATION | 

HISTORY | 

NAMEl 

VOLUME] 
CCREATION(days)] 
[EXPIRATION(days)3 
[NOTUSABLE] 
[OUTFILE(dname)] 



LISTCAT may be abbreviated? LISTC 



LISTCAT PARAMETERS 



Required Parameters 



The LISTCAT command has no required parameters. 

The LISTCAT command is issued as a job step (that is, not 
through TSO) and no parameters are specified; an entire catalog 
is listed. See the section "Order of Catalog Use* LISTCAT" for a 
description of how the catalog to be listed is selected. 

Note to TSO users: When LISTCAT is invoked from a TSO terminal 
and no operands are specified, the prefix of the TSO user 
becomes the highest level of entryname qualification and only 
those entries with a matching highest level of qualification ar& 
listed. It is as if you specified" 

LISTCATLEVEL(TSO-user-prefix) 



Optional Parameters 



[ALIAS] Cb ALTERNATEINDEX] 
Cb GENERATIONDATAGROUPHb 
Cb PAGESPACEHb PATH3Cb-S 
specifies that certa 
Only those entries w 
is, when you specify 
cluster's entry is 1 
entries are not list 
its name (that is, w 
specify an entry typ 
it i s of the specif i 
types as desired. Wh 
catalog, do not spec 



Cb CLUSTERHb DATA] 

INDEX] Cb NONVSAM] 
PACEJCb USERCATALOG] 

in types of entries are to be listed, 
hose type is speci f i ed ,i s 1 i sted (that 

CLUSTER but not DATA or INDEX, the 
i sted and its associated data and index 
ed) . When you identify an entry with 
hen you specify ENTRIES) and also 
e, the names entry is not listed unless 
ed type. You can specify as many entry 
en you want to completely 1 i st a 
i f y any entry type. 



318 0S/VS2 Access Method Services 



DATA 



LISTCAT 

ALIAS 

specifies that alias entries are to be listed. 

ALTERNATEINDEX 

specifies that entries for alternate indexes are 
listed. If ALTERNATEINDEX is specified and DATA and 
INDEX are not also specified, entries for the 
alternate-index's data and index components aren't 
1 i sted. 

Abbreviation: AIX 

CLUSTER 

specifies that cluster entries are to be listed. If 
CLUSTER is specified and DATAand INDEX are not also 
specified, entries for the cluster's data and index 
components are not listed. 

Abbreviation: CL 

specifies that entries for data components of clusters 
and alternate indexes are to be listed. If a VSAM 
object's name is specified and DATA is coded, only the 
object's data-component entry is listed. When DATA is 
the only entrytype parameter coded, the catalog's data 
component is not listed. 

GENERATIONDATAGROUP 

specifies that entries for generation data groups are 
to be 1 i sted. 

Abbreviation: GDG 

INDEX 

specifies that entries for index components of 
key-sequenced clusters and alternate indexes are to be 
listed. If a VSAM object's name is specified and INDEX 
is coded, only the object's index-component entry is 
listed. When INDEX is the only entrytype parameter 
coded, the catalog's index component is not listed. 

Abbreviation: IX 

NONVSAM 

specifies that entries for nonVSAM data sets are to be 
listed. If a generation data group's name and nonVSAM 
are specified, the generation data sets associated 
with the generation data group are listed. 

Abbreviation: NVSAM 

PAGESPACE 

specifies that entries for page spaces are to be 
li sted. 

Abbreviation: PGSPC 



PATH 
SPACE 



specifies that entries for paths are listed. 

specifies that entries for volumes containing data 
spaces defined in this catalog are to be listed. 
Candidate volumes are included. If entries are 
identified by entryname, SPACE can be coded only when 
no other entrytype parameter is coded. 

Abbreviation: SPC 

USERCATALOG 

specifies that catalog connectors are to be listed. 
The usei — catalog connector entries are in the master 
catalog. (Usei — catalog connector entries can also be 
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in a user catalog* but the 0S/VS2 system does not 
recognize them when searching for a user catalog.) 

Abbreviation: UCAT 

ALL | ALLOCATION | HISTORY | NAME | VOLUME 

specifies the fields to be included for each entry listed. 
"Appendix B- Interpreting LISTCAT Output Listings" shows 
the listed information that results when you specify 
nothing (which defaults to NAME), ALL, VOLUME, ALLOCATION, 
and HISTORY. 

ALL 

specifies that all fields are to be listed. 

ALLOCATION 

specifies that the information provided by specifying 
VOLUME and detailed information about the allocation 
are to be listed. The information about ,allocati on is 
listed only for data and index component entries. 

Abbreviation: ALLOC 

HISTORY 

specifies that only the following information is to be 
listed for each entry J name, entry type, ownerid, 
creation date, expiration date, and for a recoverable 
catalog's entries, the catalog recovery area's volume, 
device type, and control interval number. It can be 
specified for CLUSTER, DATA, INDEX, ALTERNATEINDEX, 
PATH, GENERATIONDATAGROUP, PAGESPACE, and NONVSAM. 

Abbreviation: HIST 

NAME 

specifies that the name and entry type of the entries 
are to be li sted. 

Note to TSO users: Only the name of each entry 
associated with the TSO user's prefix is listed when 
no other parameters are coded. 

Some entrytypes are listed along with their associated 
entries. The entrytype and name of the associated 
entry follows the listed entry's name. For details, 
see "ASNi Associations Group" in "Appendix B* 
Interpreting LISTCAT Output Listings." 

VOLUME 

specifies that the information provided by specifying 
HISTORY, and the volume serial numbers and device . 
types allocated to the entries are to be listed. 
Volume information is only listed for data and index 
component entries, data-space (volume) entries, 
nonVSAM data-set entries, and usei — catalog connector 
entri es. 

Note to TSO users: Only the name and volume serial 
numbers associated with the TSO user's prefix are 
listed when no other parameters are coded. 

Abbreviation: VOL 

CATAL0G(catnameC/password3 ) 

specifies the name of the catalog that contains the entries 
that are to be listed. If CATALOG is coded, only entries 
from that catalog are listed. See "Order of Catalog Use : 
LISTCAT" for information about the order in which catalogs 
are searched. 

cat name 

is the name of the catalog. 
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password 

specifies the read-level or higher-level password of 
the catalog that contains entries to be listed. If the 
entries to be listed are password protected, a 
password must be supplied either through this 
parameter or through the ENTRIES parameter. If 
passwords are to be listed, you must specify the 
master password. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 

CREATION(days) 

specifies that entries of the indicated type (CLUSTER, 
DATA, etc.) are to be listed only if they were created the 
specified number of days ago or earlier. 

days 

specifies the number of days ago. This value can be 
expressed in decimal, hexadecimal, or binary. If it is 
expressed in hexadecimal or binary, it must be 
preceded by X or B and be enclosed in single quotation 
marks. The maximum number that can be specified is 
9999; zero indicates that all entries are to be 
listed. 

Abbreviation: CREAT 

ENTR I ESC en try name C/password 3 [b en try name [ /password] . . . ] ) | 

LEVEL(level) 

specifies the names of entries to be listed. The entire 
catalog is listed when all of the following are true: 

• ENTRIES, LEVEL, NOTUSABLE, CREATION, and EXPIRATION are 
not coded. 

• No entrytype parameter is coded. 

• TSO is not being used to issue the LISTCAT command. 

Entries are only listed from an OS CVOL if the ENTRIES or 
LEVELS parameter is specified and: 

• The CATALOG parameter is not specified 

• No JOB or STEPCAT DD is specified 

• The higher level qualifier of the name specified using 
ENTRIES or LEVELS i s the alias of a CVOL 

ENTRIES (en try name [/password] 

[b entryname[/password] . . . ] ) 

specifies the name or generic name of each entry to be 
listed. When you want to list the entries that describe a 
user catalog, the catalog's volume must be physically 
mounted. You then specify the catalog's name as the 
entryname. If you want data space information, you must 
specify the volume serial number (as the entryname) of the 
volume containing the data space; you must also specify 
SPACE and no other entrytype parameters. 

If the ENTRIES parameter specifies a generic name, a 
maximum of 1456 entries can be listed. 

Note to TSO users: When you specify an incomplete 
qualified entryname, TSO prompts you to complete it. 

password 

specifies a password when the entry to be listed is 
password protected and a password is not specified 
with the CATALOG parameter. The password must be any 
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of the entry's passwords. The entry's protection 
attributes are listed only when you specify the 
entry's (or its catalog's) master password. When you 
don't supply a password for a password-protected 
entry, the operator or TSO terminal user is prompted 
for the entry's password. You cannot supply a password 
for these types of entries ' nonVSAM data set, 
generation data group, alias, usei — catalog connector, 
and data space. 

Abbreviation: ENT 

LEVEL( level) 

specifies that all entries that match the level of 
qualification specified by (level) are to be listed 
irrespective of the number of qualifications after the 
level. If a generic level name is specified, one qualifier 
replaces the *. 

Notes The * does not necessarily specify the last 
(rightmost) level of qualifications. 

As an example, suppose the VSAM catalog contains the 
following names 1 

1. A.A.B 

2. A.B.B 

3. A.B.B.C 

4. A.B.B.C.C 

5. A.C.C 

6. A.D 

7. A.E 

If ENTRIES(A.*) is specified, then entries 6 and 7 would be 
listed. If ENTRIES(A.*.B) is specified, then entries 1 and 
2 would be listed. If LEVEL(A.*.B) is specified, then 
entries 1,2,3 and 4 would be listed. If LEVEL(A) is 
specified, then entries 1,2,3,4,5,6 and 7 would be listed. 

If the LEVEL parameter is specified, a maximum of 1456 
entries can be listed. 

Note to TSO users: TSO will prefix the userid to the 
specified data-set name when the ENTRIES parameter is 
specified with an unqualified entry name. The userid is not 
prefixed when the LEVEL parameter is specified. 

Abbreviation: LVL 

EXPIRATIONtdays) 

specifies that entries of the indicated type (CLUSTER, 
DATA, etc.) are to be listed only if they will expire the 
specified number of days from now or earlier. 

days 

specifies the number of days from now. This value can 
be expressed in decimal, hexadecimal, or binary. If it 
is expressed in hexadecimal or binary, it must be 
preceded by X or B and be enclosed in single quotation 
marks. The maximum number that can be specified is 
9999 and it indicates that all entries are to be 
listed. Any value that exceeds the year 2000 will 
default to 99.999 (yyddd). Zero indicates that only 
entries that have already expired are to be listed. 

Abbreviation: EXPIR 
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NOTUSABLE 

specifies that only those data and index entries which have 
the "unusable" indicator on are to be listed. A data or 
index component . i s marked "unusable" when a system failure 
occurs that results in damage to the entry's cataloged 
i nformati on. 

When the cataloged information is reset* the damaged entry 
and its backup copy (in the catalog recovery area) might 
not match when the space allocation information is 
compared. VSAM marks the catalog entry "unusable" until the 
space allocation information is corrected. See "Restoring 
Catalog Entries After System Failure" for more details. 

Abbreviation: NUS 

OUTFILEtdname) 

specifies a data set, other than the SYSPRINT data set, to 
receive the output produced by LISTCAT Cthat is, the listed 
catalog entries). Completion messages produced by Access 
Method Services &r& sent, along with your job's JCL and 
input statements, to the SYSPRINT data set. 

dname identifies a DD statement that describes the 
alternate output data set. If OUTFILE is not specified, the 
entries are listed in the SYSPRINT data set. If an 
alternate data set is specified, it must meet the 
requirements shown under "Output Data Sets" in the 
"Introduction." 

Abbreviation: OFILE 
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LISTCAT EXAMPLES 

Listing a Key-Sequenced Cluster's Entry: Example 1 

In this example* a key-sequenced cluster entry is listed. 

//LISTCAT1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT-A 
//SYSIN DD x 
LISTCAT - 

ENTRIESCD40. EXAMPLE. KSDS1) - 

CLUSTER - 

ALL 
/* 

The job control language statements are- 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The LISTCAT output will also be 
sent to the SYSPRINT output device. 

The LISTCAT command lists the cluster's catalog entry. It is 
assumed that the high level of the qualified cluster name is the 
same as the alias of the catalog D27UCAT1; this naming 
convention directs the catalog search to the appropriate 
catalog. Its parameters are : 

• ENTRIES, which identifies the entry to be listed. 

• CLUSTER* which specifies that only the cluster entry is to 
be listed. If CLUSTER had not been specified* the cluster's 
data and index entries would also be listed. 

• ALL* which specifies that all fields of the cluster entry 
are to be listed. 

Alter a Catalog Entry, Then List the Modified Entry: Example 2 

In this example* the freespace attributes for the data component 
(KSDATA) of cluster MYDATA are modified. Next* the cluster 
entry* data entry, and index entry of MYDATA are listed to 
determine the effect* if any* the modification has on the 
cluster's other attributes and specifications. 



//LISTCAT2 


JOB 


• • * 








//JOBCAT 


DD 


DSNAME: 


=D27UCAT1, 


.DISP: 


=SHR 


//STEP1 


EXEC 


pgm=: 


EDCAMS 






//SYSPRINT 


DD 


SYS0UT= 


= A 






//SYSIN 


DD 


x 








ALTER 














KSDATA - 










FREESPACEC10 


10) 






IF LASTCC = 


= - 










THEN ■ 












LISTCAT - 












ENTRIES(MYDATA) 


- 








ALL 









/x 
The job control language statements are: 

• JOBCAT DD* which makes a catalog available for this job* 
D27UCAT1. 

• SYSPRINT DD* which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The LISTCAT output will also be 
sent to the SYSPRINT output device. 
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The ALTER command modifies the freespace specifications of the 
key-sequenced VSAM cluster MYDATA. The command's parameters are : 

• KSDATA, which is the entryname of the data component being 
altered. KSDATA identifies the data component of a 
key-sequenced VSAM cluster, MYDATA. In order to alter a 
value that applies only to the cluster's data component* 
such as FREESPACE does, you must specify the 
data-component's entryname. 

• FREESPACE, which specifies the new freespace percentages for 
the data-component's control intervals and control areas. 

The IF ... THEN command sequence verifies that the ALTER command 
completed successfully before the LISTCAT command executes. 

The LISTCAT command lists the cluster's entry and its data and 
index entries. Its parameters are : 

• ENTRIES, which specifies the entryname of the object being 
listed. Because MYDATA is a key-sequenced cluster, the 
cluster entry, its data entry, and its index entry are 

li sted. 

• ALL, which specifies that all fields of each entry ar& to be 
listed. 



List Catalog Entries: Example 3 



In this example, each catalog entry with the name 
"GENERIC*. ABLE" is listed, where "*" is any 1 to 8 character 
simple name. The name "GENERIC. *. ABLE" is a generic name, and 
this example illustrates how all catalog entries with the same 
generic name are listed. 



//LISTCAT3 




JOB 


... 


//JOBCAT 




DD 


DSNAME=D27UCAT1,DISP=SHR 


//STEP1 




EXEC 


PGM=IDCAMS 


//SYSPRINT 




DD 


SYS0UT=A 


//SYSIN 




DD 


* 


LISTCAT 


- 






ENTRIES(GENERIC*.ABLE) - 




ALL 




/* 









The job control language statements are'- 

• JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer and the LISTCAT output are to be sent. 

The LISTCAT command lists each catalog entry with the name 
GENERIC*. ABLE, where "*" is any 1 to 8 character simple name. 
Its parameters are'* 

• ENTRIES, which specifies the entryname of the object to be 
listed. Because GENERIC *. ABLE is a generic name, more than 
one entry might be listed. 

• ALL, which specifies that all fields of each entry are to be 
listed. 
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LISTCRA 



The format of the LISTCRA command is: 



LISTCRA 



INFILECdnameCb dname. . . 3 ) 

C CAT ALOG C ca t name C/ pas sword 3b dname) 3 

[COMPARE INOCJDMPARE 3 

[DUMP 1 NAME 1 SEQUENT! ALDUMP3 

CMASTERPWt password ) 3 

[0UTFILE(dname)3 



LISTCRA may be abbreviated: LISTR, 



LISTCRA PARAMETERS 



Required Parameters 



INFILECdnameCb dname. . . 3 ) 

identifies the DD statement(s) that describes the catalog 
recovery area's volume. You can list or compare more than 
one catalog recovery area. However, if COMPARE is 
specified, all volumes whose catalog recovery areas are 
listed must be owned by the same VSAM catalog. 

Note: The dname list for the INFILE parameter is limited to 
9 dnames. 



Abbreviation: IFILE 



Optional Parameters 



CATAL0G(catnameC/password3b dname) 

identifies the catalog that owns the volume(s) identified 
with the INFILE parameter. The CATALOG parameter is 
required when you specify the COMPARE option either with 
the DUMP or NAME output format. CATALOG cannot be specified 
with SEQUENTIALDUMP. 

password 

When the catalog is password protected, you must 
supply the catalog's master password. The password is 
required even though the master catalog's password may 
have been supplied in the MASTERPW parameter. 

dname 

When CATALOG is specified, you must describe and 
allocate the catalog to be compared with a DD 
statement, dname identifies the catalog's DD 
statement, and is required when you specify the 
CATALOG parameter. You cannot specify JOBCAT or 
STEPCAT as the dname. However, if the catalog being 
compared is not the VSAM master catalog, you must also 
identify the catalog by a STEPCAT or JOBCAT DD 
statement in addition to the DD statement referenced 
by dname. 

If the catalog information is entered incorrectly, the 
NOCOMPARE default is taken, and all of the CRA records are 
1 i sted. 

Abbreviation: CAT 

COMPAREl NOCOMPARE 

specifies whether the list is to be limited to those 
entries in the catalog recovery area which do not match 
their corresponding catalog entries. 
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LISTCRA 

When you specify COMPARE, only those entries which do not 
match are listed. All of the catalog's entries are 
compared, except the catalog's self-describing records. You 
must identify the catalog (that contains the to-be-compared 
catalog entries) with the CATALOG parameter. 

When you specify NOCOMPARE (or allow it to default), all of 
the catalog recovery area's records are listed. 

The COMPARE parameter cannot be specified if you specify 
SEQUENTIALDUMP. 

Note: if you specify the COMPARE option, page space entries 
will always result in a mismatch. This is a normal 
condition and does not require any corrective action. The 
mismatch is due to the OPEN indicator not being set in the 
page space record in the CRA, whereas it is set in the 
catalog. 

See "Appendix D : Interpreting LISTCRA Output Listings" for 
examples of each type of output listing. 

Abbreviations: CMPR and NCMPR 

DUMP | NAME I SEQUENTIALDUMP 

specifies the amount of cataloged information to be listed. 

DUMP 

specifies that each listed entry is printed in its 
entirety in both hexadecimal and character form, 
sorted alphameri cally and grouped. 

specifies that each listed entry includes only the 
entry's name, its volume serial numbers, and the name 
and entry type of each associated entry. All listed 
entries are sorted alphameri cally and grouped. 

SEQUENTIALDUMP 

specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 
Records are listed in the sequence each appears in the 
catalog recovery area. 

Abbreviation: SDUMP 

The DUMP, NAME, SEQUENTIALDUMP, COMPARE, and NOCOMPARE 
options can be specified to produce five different kinds of 
output listing. See "Appendix D: Interpreting LISTCRA 
Output Listings" for examples of each type of listing. 

MASTERPWCpassword) 

specifies the master catalog's master password. You must 
supply the master catalog's master password with the 
MASTERPW parameter when the master catalog is 
password-protected. 

Abbreviation: MRPW 

OUTFILE(dname) 

identifies the DD statement that describes an alternate 
output data set. See "Output Data Sets" for more details 
about alternate output data sets. When OUTFILE is not 
specified, the listing is printed on the output device 
described with the SYSPRINT DD statement. When OUTFILE is 
specified, the listing produced by LISTCRA is sent to the 
alternate output data set; the remainder of the Access 
Method Services output is printed on the output device 
described with the SYSPRINT DD statement. Refer to 
"Appendix D> Interpreting LISTCRA Output Listings" for an 
example of the use of the OUTFILE parameter. 

Abbreviation: OFILE 
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LISTCRA EXAMPLE 



Listing a Catalog Recovery Area: Example 1 



This example lists the catalog recovery areas for those volumes 
owned by the VSAM master catalog, AMASTCAT, in dump format, and 
compares those catalog recovery areas with the actual catalog 
records themselves. 

//LISTAREA JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//CRAV0L1 DD DISP=OLD,VOL=SER=SG2001,UNIT=2314 
//CRAV0L2 DD DISP=0LD, VOL=SER=VSER04,UNIT=3330 
//CATVOL DD DSNAME=AMASTCAT,DISP=OLD 
//SYSIN DD x 
LISTCRA - 

INFILEC - 
CRAV0L1 - 
CRAV0L2) - 

MASTERPW(MCATMRPW) - 

COMPARE - 

DUMP - 

CATALOG(AMASTCAT|/MCATMRPW CATVOL) 

The job control language statements ar&' 

• CRAV0L1 DD, which identifies and allocates the volume that 
contains the first catalog recovery area to be listed. 

• CRAV0L2 DD, which identifies and allocates the volume that 
contains the second catalog recovery area to be listed. 

• CATVOL DD, which identifies and allocates the catalog to be 
compared against, and makes the catalog available to LISTCRA 
as a data set. Because this example is listing the master 
catalog, no STEPCAT or JOBCAT DD statement is required. 
However, if the example were listing a user catalog, a 
STEPCAT or JOBCAT DD statement would be required in addition 
to the CATVOL DD statement to describe the user catalog as a 
catalog. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The listing produced by LISTCRA 
is also sent to this same output device. 

The LISTCRA command causes the catalog recovery areas on volumes 
SG2001 and VSER04 to be listed and their contents compared with 
the VSAM system catalog AMASTCAT. The LISTCRA command's 
parameters are- 

• INFILE, which is required and specifies the catalog recovery 
areas to be listed by identifying the DD statement that 
describes each CRA's volume. 

• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to open the 
catalog recovery areas for LISTCRA processing. 

• COMPARE, which specifies that the catalog records are to be 
compared with their copies in the catalog recovery areas. 

• DUMP, which specifies that the results of the record 
comparison (that is, the LISTCRA output listing) is to be 
printed in dump format. 

• CATALOG, which is required (because the COMPARE option was 
specified) and identifies the catalog to be compared against 
by identifying the DD statement that describes and allocates 
the catalog as a data set. 
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PRINT 



The format of the PRINT command is: 



PRINT 



{INFILE(dnameC/password3 ) | 

I ND AT AS ETC en try name C/password] )} 

COUTFILE(dname)] 

[ CHARACT ER I DUMP I HEX ] 

C FROMKEY ( keyTFFROMADDRESS (address ) 
FROMNUMBER ( number ) | SKIP( count ) ] 

CTOKEY(key)|TOADDRESS(address)| 
TONUMBERC number ) I COUNT (count ) 3 



PRINT PARAMETERS 



Required Parameters 



INFILE(dnameC/password3 ) I 
INDATASETCentrynameC/password] ) 

identifies the data set or component to be printed. 

INFILE(dname[/password] ) 

specifies the name of the DD statement that identifies 
the data set or component. You can 1 i st. a base cluster 
in alternate-key sequence by specifying a path name as 
the data set name in the DD statement. See the section 
"Printing Data Sets" for information on DCB parameters 
required for nonVSAM data sets. 

Abbreviation: IFILE 

INDATASET( en trynameC /password] ) 

specifies the name of the entry to be printed. If 
INDATASET is specified, the entryname is dynamically 
allocated. You can list a base cluster in 
alternate-key sequence by specifying a path name as 
entryname. 



password 

If a VSAM data set o 
protected, a passwor 
password to be suppl 
the catalog if you a 
read- or highei — leve 
component if the dat 
catalog. You can spe 
the cluster if you a 
password-protected c 
applicable only to V 
components. 

Abbreviation: IDS 



r component is password 
d must be supplied. The 
i ed is the master password of 
re listing a catalog, or the 
1 password of the data set or 
a set or component i s not a 
cify the master password of 
re listing a component of a 
luster. Passwords are 
SAM data sets and their 



Optional Parameters 



CHARACTER | DUMP | HEX 
specifies the 



format of the listing. 



CHARACTER 

specifies that each byte in the logical record is to 
be printed as a character. Bit patterns not defining a 
character are printed as periods. Key fields are 
listed in character format (see Figure 10). 

Abbreviation: CHAR 
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IDCAMS SYSTEM SERVICES 



TIME: 19:26:13 



03/08/75 PAGE 6 



LISTING OF DATA SET -EXAMPLE. LISTC. DATA 

RBA OF RECORD - 

ABCD000000000001ABCDEFGHIJKLMNOPOTSTUVIWZ0123456789ABCDEFGHIJKLMNOPQRST1JVWXY 

6789ABCDEFGHIJKLMtraPQRSTUVWXYZ0123«6789ABCDEFGHIJKLTINOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123«6789ABCDEFGH 

IJKLMNOP<WSTUVVKYZ0123456789ABCDEFGHIJKLMNOPQRSTUVI«YZ0123«6 

UVWXYZ0123456789ABCDEFGHIJKLMNOPQRST. ... 

Figure 10. Character Format 



DUMP 



specifies that each byte in the logical record is to 
be printed in both hexadecimal and character format. 
In the character portion of the listing, bit patterns 
not defining a character are printed as periods. Key 
fields are listed in hexadecimal format (see 
Fi gure 11) . 



IDCAMS SYSTEM SERVICES 



TIME: 19:25:14 



03/08/75 PAGE 2 



LISTING OF DATA SET -EXAMPLE. LISTC 

F0F0F0F0F0F0F0F0F0F0F0F1 

F0F0F0F0 F0F0F0F0 F0F0F0F1 C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 

E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 

D8D9E2E3 E4E5E6E7 F8F9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 

D4D5D6D7 D8D9E2E3 E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 

C9D1D2D3 04D5D6D7 D8D9E2E3 E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 

C5C6C7C8 C9D1D2D3 D4D5D6D7 D8D9E2E3 E4E5E6E7 E8E9F0F1 F2F3F4F5 

C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 D8D9E2E3 E4E5E6E7 E8E9F0F1 

F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 D8D9E2E3 E4E5E6E7 

F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 D8D9E2E3 

E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 

E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 

D8D9E2E3 E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 
D4D5D6D7 D8D9E2E3 00000000 

Figure 11. Dump Format 



KEY OF 


RECORD - 


0000 


C1C2C3C4 


0020 


D8D9E2E3 


0040 


D4D5D6D7 


0060 


C9D1D2D3 


0080 


C5C6C7C8 


00A0 


C1C2C3C4 


ooco 


F6F7F8F9 


00E0 


F2F3F4F5 


0100 


E8E9F0F1 


0120 


E4E5E6E7 


0140 


D8D9E2E3 


0160 


D4D5D6D7 


0180 


C9D1D2D3 



*ABCD000000000001ABCDEFGHIJKLMNOP* 
*QRSTUVWXYZ0123456789ABCDEFGHIJKL* 
*MNOPQRSTUVWXYZ0123456789ABCDEFGH* 
*IJKLMNOPQRSTUVWXYZ0123456789ABCD* 
*EFGHIJKLMNOPQRSTUVWXYZ0123456789* 
*ABCDEFGHIJKLMN0PQRSTUVWXYZ0 1 2345* 
K6789ABCDEFGHIJKLMNOPQRSTUVWXYZ01* 
*23456789ABCDEFGHIJKLMN0PQRSTUVWX* 
*YZ0123456789ABCDEFGHIJKLMNOPQRST* 
*UVWXYZ0123456789ABCDEFGHIJKLMNOP* 
*QRSTUVWXYZO 1 23456 789ABCDEFGHI JKL* 
KMNOPQRSTUVWXYZO 1 23456789ABCDEFGH* 
*IJKLMN0PQRST * 



HEX 



specifies that each byte in the logical record i 
be printed as two hexadecimal digits. Key fields 
listed in hexadecimal format (see Figure 12) 



s to 
s are 



ibCAMS SYSTEM SERVICES 



TIME: 19:26:13 



03/08/75 PAGE 4 



LISTING OF DATA SET -EXAMPLE. LISTC. DATA 

RBA OF RECORD - 

C1C2C3C4F0F0F0F0F0F0F0F0F0F0F0F1C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C9D1D2D3D4D5D6D7D8D9E2D3D4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9FOF1F2F3F4F5 

F6F7F8F9ClC2C3C4C5C6C7C8C9DlD2D3D«D5D6D7D8D9E2E3E4E5E6E7E8E9FOFlF2F3F4F5F6F7F8F9ClC2C3C<tC5C6C7C8C9DlD2D304D5D6D7D8D9E2E3 

E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D203D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C9D1D203D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0FIF2F3F4F5F6F7F8F9CIC2C3C4C5C6C7C8C9DID2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5 

F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F-F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D203D4D5D6D7D8D9E2E3 

E4E5E6E7E8E9FOFlF2F3F4F5f6F7F8F9ClC2C3C4C5C6C7C8C9DlD2D3D4D5D607D809E2E300000000 

Figure 12. Hex Format 



FR0HKEY( key ) I FROMADDRESS (address ) I 
FROMNUHBER(number)|SKIP(count) 

specifies the location in the 
which listing is to start. If 



data set being listed from 
no value is specified, the 
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listing begins with the first logical record in the data 
set or component. The only value that can be specified for 
a SAM data set is SKIP. 

FROMKEY(key) 

specifies the key of the first record you want listed. 
You can specify generic keys — that is, keys shorter 
than that defined for the data set. If you specify 
generic keys, listing begins at the first record whose 
key matches that portion of the key you specified. 
(You cannot specify a key longer than that defined for 
the data set. If you do, the listing is not 
performed.) If the specified key is not found, the 
next higher key is used as the starting point for the 
1 i sti ng. 

FROMKEY can be specified only when an alternate index, 
a key-sequenced VSAM data set, a VSAM catalog, or an 
i ndexed-sequenti al (ISAM) nonVSAM data set is being 
printed. When you specify FROMKEY, you cannot also 
specify TOADDRESS to identify the last record to be 
pri nted. 

key can contain 1 to 255 EBCDIC characters, key must 
be enclosed in single quotation marks if it contains 
commas, semicolons, blanks, parentheses, or slashes. A 
single quotation mark within a key must be coded as 
two single quotation marks if the key is enclosed in 
single quotation marks. You can code key in 
hexadecimal form where the hexadecimal value is 
enclosed in single quotation marks and preceded by an 
X — for example, X'C2C1C8'. key can contain up to 255 
hexadecimal characters. 

Abbreviation: FKEY 

FROMADDRESS (address) 

specifies the relative byte address (RBA) of the first 
record you want listed. The RBA value must be the 
beginning of a logical record. If you specify this 
parameter for a key-sequenced data set, the listing 
will be in physical sequential order instead of in 
logical sequential order. FROMADDRESS can be specified 
only for VSAM key-sequenced or entry-sequenced data 
sets or components. FROMADDRESS cannot be specified 
when the data set is accessed through a path. 
FROMADDRESS cannot be specified for a key-sequenced 
data set with spanned records if any of those spanned 
records are to be accessed. 

Abbreviation: FADDR 

FROMNUMBERC number) 

specifies the relative-record number of the first 
record you want printed. 

Abbreviation: FNUM 

SKIPCcount) 

specifies the number of logical records you want to 
skip before the listing of records begins. For 
example, if you want the listing to begin with record 
number 500, you specify SKIP(499). SKIP should not be 
specified when you are accessing the data set through 
a path; the results are unpredictable. 

address, number, and count can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n'); the 
expression cannot be longer than one fullword (eight 
decimal or hexadecimal numbers, or 32 binary numbers). 

OUTFILE(dname) 

identifies an alternate output data set — that is, an output 
data set other than SYSPRINT. For dname substitute the name 
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of the JCL statement that identifies the alternate output 
data set.. The standard Access Method Services output data 
set for listings, which is identified by the DD name 
SYSPRINT, is the default. The output data set must meet the 
requirements stated in the "Introduction" under "Output 
Data Sets." 

Abbreviation: OFILE 

TOKEY(key)|TOADDRESS(address)| 

TONUHBER(number) |CQUNT(count) 

specifies the location in the data set being listed at 
which listing is to stop. If no value is specified, the 
listing ends with the logical end of the data set or 
component. The only value that can be specified for a 
sequential data set is COUNT. The location at which the 
listing is to stop must follow the location at which the 
listing is to begin. 

The ending delimiter must be consistent with the starting 
delimiter. For example, if FROMADDRESS is specified for the 
starting location, neither TOKEY nor TONUMBER may be 
specified for the location. Similarly, if FROMNUMBER is 
specified for the starting location, neither TOKEY nor 
TOADDRESS may be specified for the ending location. 

TOKEY(key) 

specifies the key of the last record to be listed. You 
can specify generic keys — that is, keys shorter than 
that defined for the data set. If you specify generic 
keys, listing stops after the last record is listed 
whose key matches that portion of the key you 
specified. (You cannot specify a key longer than that 
defined for the data set. If you do, the listing is 
not performed.) If the specified key is not found, the 
next lower key is used as the stopping point for the 
1 i st i ng. 

TOKEY can be specified only when an alternate index, a 
key-sequenced VSAM data set, a VSAM catalog, or an 
i ndexed-sequent ial (ISAM) nonVSAM data set is being 
pri nted. 

key can contain 1 to 255 EBCDIC characters, key must 
be enclosed in single-quotation marks if it contains 
commas, semicolons, blanks, parentheses, or slashes. A 
single-quotation mark within a key must be coded as 
two single-quotation marks if the key is enclosed in 
single quotation marks. You can code key in 
hexadecimal form where the hexadecimal value is 
enclosed in sing-quotation marks and preceded by an 
X — for example, X'C2C1C8'. key can contain up to 255 
hexadecimal characters. 

TOADDRESSCaddress) 

specifies the relative byte address (RBA) of the last 
record you want listed. Unlike FROMADDRESS, the RBA 
value does not need to be the beginning of a logical 
record. The entire record containing the specified RBA 
is printed. If you specify this parameter for a 
key-sequenced data set, the listing will be in 
physical sequential order instead of in logical 
sequential order. TOADDRESS can be specified only for 
VSAM key-sequenced or entry-sequenced data sets or 
components. TOADDRESS cannot be specified when the 
data set is accessed through a path. .TOADDRESS cannot 
be specified for a key-sequenced data set with spanned 
records if any of those spanned records are to be 
accessed. 

Abbreviation: TADDR 
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TONUMBER(number) 

specifies the relative-record number of the last 
record you want printed. 

Abbreviation: TNUM 

COUNT(count) 

specifies the number of logical records to be listed. 
COUNT should not be specified when you are accessing 
the data set through a path; the results sre 
unpredictable. 

address* number, and count can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n'); the expression cannot 
be longer than one fullword (eight decimal or hexadecimal 
numbers, or 32 binary numbers). 
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PRINT EXAMPLES 

Print a Key-sequenced Cluster's Data Records: Example 1 

In this example, the data records of a key-sequenced cluster, 
D40 . EXAMPLE. KSDS1 , are printed in dump format. That is, each 
character of the record is printed in its hexadecimal and 
alphameric forms. 

//PRINT1 JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD x 

PRINT - 

INDATASETCD40.EXAMPLE.KSDS1) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The listing produced by PRINT is 
sent to the same output device. 

The PRINT command prints data records of the key-sequenced 
cluster, D40. EXAMPLE. KSDS1. Its parameter \s- 

• INDATASET, which names the data set to be printed. Since the 
data set is cataloged in D27UCAT1 and the high-level 
qualifier of the data set is the name of the alias of 
D27UCAT1, Access Method Services can dynamically allocate 
the cluster without the need of JOBCAT or STEPCAT DD 
statements. 

Because neither FROMADDRESS, FROMKEY, SKIP, TOKEY, TOADDRESS, or 
COUNT is specified, Access Method Services assumes that all of 
the cluster's data records are to be printed. 

Because neither HEX nor CHAR was specified, Access Method 
Services prints each record in the DUMP format. An example of 
the printed record is shown in Figure 13. 



KEY OF RECORD - 00F0F0F0F0F1C9E240C4C1405CC6C9 

0000 00F0F0F0 F0F1C9E2 40C4C140 5CC6C9D3 C540C9F0 C6F8F05C 40F5F040 D9C5C3D6 *.00001IS DA *FILE IOD80* 50 RECO* 

0020 JD9ME240 D6C640F6 F940C3C8 C1D9E240 E6C9E3C8 40D2C5E8 40C9D540 D7D6E240 *RDS OF 69 CHARS WITH KEY IN POS * 

0040 F160F1F1 4B000000 00000000 00000000 *1-11 

Figure 13. An Example of the Printed Record in DUMP Format 



334 0S/VS2 Access Method Services 



PRINT 

Copy Records From a NonVSAM Data Set Into an Entry-sequenced VSAM Cluster, Then 
Print the Records: Example 2 

In this example, the first fifteen records from a nonVSAM data 
set, EXAMPLE. NONVSAM, are copied into an entry-sequenced 
cluster, D50. EXAMPLE. ESDS1. If the records were copied 
correctly, the cluster's records are printed in hexadecimal 
format. Finally, even if the records were not copied correctly, 
the nonVSAM data set's first fifteen records are printed in 
character format. 

//PRINT2 JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 
// DD DSNAME=D27UCAT2,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 

//VSDSET2 DD DSNAME=D50 . EXAMPLE. ESDS1 ,DISP=0LD 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
REPRO - 

INDATASETCEXAMPLE. NONVSAM) - 

0UTFILECVSDSET2/DEPT27U) - 

C0UNTC15) 

IF LASTCC = - 
THEN - 
PRINT - 

INFILE(VSDSET2) - 

HEX 

PRINT - 

INDATASETCEXAMPLE. NONVSAM) - 
C0UNTC15) - 
CHARACTER 
/* 

The job control language statements are'- 

• JOBCAT DD, which makes two catalogs available for this job* 
D27UCAT1 and D27UCAT2. Concatenated JOBCAT DD statements 
were used to identify both catalogs. 

• VSDSET2 DD, which identifies the entry-sequenced VSAM 
cluster, D50 . EXAMPLE. ESDS1, that the records are copied 
i nto . 

Note* If the AMP=(BUFND=n) parameter was specified, 
performance would improve when the data set's records are 
accessed. BUFND was allowed to default in this example, 
because only 15 records are being processed. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The listing produced by the PRINT 
commands is sent to the same output device. 

The REPRO command copies the first fifteen records from the 
input data set, EXAMPLE. NONVSAM, into the output entry-sequenced 
cluster, D50. EXAMPLE. ESDS1 . Its parameters are: 

• INDATASET, which identifies the input data set, 

EXAMPLE. NONVSAM. Because a JOBCAT DD statement is included 
with the job, VSAM will search for the catalog entry 
describing the nonVSAM data set in either D27UCAT1 or 
D27UCAT2 user catalog, or in the master catalog. 

• OUTFILE, which points to the VSDSET2 DD statement. The 
VSDSET2 DD statement identifies the output data set, 

D50. EXAMPLE. ESDS1. VSAM assumes that D50 . EXAMPLE. ESDS1 is 
cataloged either in D27UCAT1 or D27UCAT2 user catalog, or in 
the master catalog. 
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• COUNT, which specifies that fifteen records are to be 
copied. Because the SKIP parameter was not specified, Access 
Method Services assumes that the first fifteen records are 
to be copied. FROMNUMBER, FROMADDRESS, and FROMKEY cannot be 
specified for a nonVSAM data set. The records are always 
added after the last record in the output data set. 

The IF ... THEN command sequence verifies that the REPRO command 
completed successfully before the first PRINT command executes. 

The first PRINT command prints the records in the 
entry-sequenced cluster, D50 . EXAMPLE. ESDS1 . Its parameters are: 

• INFILE, which points to the VSDSET2 DD statement. The 
VSDSET2 DD statement identifies the cluster, 

D50. EXAMPLE. ESDS1. VSAM assumes that the cluster is 
cataloged either in D27UCAT1 or D27UCAT2 user catalog, or in 
the master catalog. 

• HEX, which specifies that each record is to be printed as a 
group of hexadecimal characters. An example of the printed 
record is shown in Figure 14. 



RBA OF RECORD - 

C206E8C50940404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040 

4040404040404040404040404040404040404040 

Figure 14. An Example of the Printed Record in Hexadecimal 



Mote? The IF ... THEN command sequence ends with the HEX 
parameter, because no continuation character follows this 
parameter. If you want two or more Access Method Services 
commands to execute only when the IF statement is satisfied, 
enclose the commands in a DO... END command sequence. 

The second PRINT command, which executes even if the REPRO 
command failed, prints the first fifteen records of the nonVSAM 
data set, EXAMPLE. NONVSAM. Its parameters are' 

• INDATASET, which identifies the nonVSAM data set 
EXAMPLE. NONVSAM. VSAM will search for the catalog entry in 
either D27UCAT1 or D27UCAT2 user catalog or in the master 
catalog. 

• COUNT, which specifies that fifteen records are to be 
printed. Because SKIP was not specified, Access Method 
Services assumes that the first fifteen records are to be 
printed. FROMNUMBER, FROMADDRESS, or FROMKEY cannot be 
specified for a nonVSAM sequential data set. 

• CHARACTER, which specifies that each record is to be printed 
as a group of alphameric characters. An example of the 
printed record is shown in Figure 15. 



RECORD SEQUENCE NUMBER - 3 
CLARK 

Figure 15. An Example of a Printed Alphameric Character Record 
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Print a VSAM Catalog: Example 3 



This example shows various ways to print a VSAM catalog. You may 
find this function of the PRINT command helpful in the event of 
a problem with your catalog. 

//PRINT3 JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=0LD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

/* PRINT THE LOW KEY RANGE OF THE CATALOG */ 
PRINT - 

INDATASET(D27UCAT1) - 
TOKEY (X'3F') 

/* PRINT THE HIGH KEY RANGE OF THE CATALOG */ 
PRINT - 

INDATASETCD27UCAT1) - 
FROMKEY (X'40') 

/* PRINT A SPECIFIC RECORD */ 
/* FROM THE LOW KEY RANGE */ 
PRINT - 

INDATASETCD27UCAT1) - 

FROMKEY (X'OOOOOOOE 1 ) - 

COUNT (1) 

/* PRINT THE ENTIRE CATALOG */ 
PRINT - 

INDATASETCD27UCAT1) 
/* 

The job control language statements are: 

• JOBCAT DD, which is required and which describes and 
allocates the user catalog to be printed. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. The listings produced by the 
PRINT commands are sent to the same output device. 

The first PRINT command prints the low-keyrange of the catalog. 
Its parameters are : 

• INDATASET, which specifies the name of the catalog to be 
printed. 

• TOKEY, which specifies that printing is to terminate after 
reaching a record whose key is greater than X'3F' (in its 
first byte). The low-keyrange of a VSAM catalog contains 
records with a range of keys having a value from X'OO 1 to 
X f 3F' in the first byte. 

The second PRINT command prints the hi gh-keyrange of the 
catalog. Its parameters are** 

• INDATASET, which specifies the name of the catalog to be 
pri nted. 

• FROMKEY, which specifies that printing is to begin at the 
first record whose key is X'40' or greater (in its first 
byte). The hi gh-keyrange of a VSAM catalog contains records 
with a range of keys having a value from X f 40' to X ? FF' in 
the f i rst byte. 

The third PRINT command prints one catalog record from the 
low-keyrange of the catalog. Its parameters are'- 
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• INDATASET, which specifies the name of the catalog to be 
printed. 

• FROMKEY, which specifies that printing is to begin with the 
record whose key is X f 0000000E f in the first four bytes. 
Records in the low-keyrange of a VSAM catalog have the 
number of the containing control interval as the first four 
bytes of their key. Records are 505 bytes in length and each 
record is contained in a 512-byte control interval. 

• COUNT, which specifies that only one record is to be 
pri nted. 

The fourth PRINT command prints the entire catalog, because 
there are no delimiting parameters specified. 
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REPRO 



The format of the REPRO command is ; 



REPRO 



(INFILECdnameC /password] 

Cb ENVIRQNMENT(DUMMY)])| 

INDAT AS ET( en try name [/password] 
Cb ENVIRONMENT DUMMY)])} 
(OUTFILEtdnameC/password] ) | 

OUTDATASETC en trynameC /password] )} 
C REPLACE | NOREPLACf] 
[REUSEl NOREUSE ] 
C FROMKEY( key ) | FROMADDRESS (address ) I 

FRQMNUMBER( number ) | SKIPC count ) ] 
CTOKEY(key)|TOADDRESStaddress)| 

TONUMBER ( number ) | COUNT ( count ) ] 



REPRO PARAMETERS 



Required Parameters 



INFILE(dnameC/password]Cb ENVIRONMENT (DUMMY)] ) I 
INDATASET(entrynameC/password]Cb ENVIRONMENT (DUMMY) ] ) 

identifies the data set to be copied. See the section 
"Copying Data Sets" for information on the types of data 
sets which can be copied, specific copy functions, and 
restrictions. See also the section "Copying a Catalog." 

INFILE(dnameC/password] ) 

specifies the name of the DD statement that identifies 
the data set to be copied. You can copy a base cluster 
in alternate-key sequence by specifying a path name as 
the data set name in the DD statement. See the section 
"Copying Data Sets" for information on DCB parameters 
required for nonVSAM data sets. 

Abbreviation: IFILE 

IND AT ASET( en trynameC /password] ) 

specifies the name of the entry to be copied. If 
INDATASET is specified, the entryname is dynamically 
allocated. You can copy a base cluster in 
alternate-key sequence by specifying a path name for 
entryname. 

password 

is the read- or higher — level password of the data 
to be copied. If the data set is password 
protected, the read password must be supplied. If 
a catalog is to be copied, the master password is 
required. Passwords are applicable only to VSAM 
data sets. 

Abbreviation: IDS 



ENVIRONMENT (DUMMY) 

specifies that dummy ISAM records are to be copied, 
Dummy records are records with hexadecimal 'FF* in 
first byte. If you do not include this parameter, 
dummy records will be ignored during the copy 
operation. See OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide for further information. 
ENVIRONMENT is not coded, dummy records are not 
copi ed. 

Abbreviations: ENV and DUM 

OUTFILE(dnameC/password] ) I 



the 



If 
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OUTDATASETCentrynameC/password) ) 

identifies the output data set. ISAM data sets cannot 
be specified as output data sets. 

0UTFILE(dname[/password3 ) 

specifies the name of a DD statement that 
identifies the output data set. For VSAM data 
sets, the data set name can be that of a path. 
See the section "Copying Data Sets" for 
information on DCB parameters required for 
nonVSAM data sets. If the DD statement identifies 
a SYSOUT data set, the attributes must match 
those specified in the section* "Output Data 
Sets." 

Abbreviation: OFILE 

OUTDATASETCentrynameC/password]) 

specifies the name of the output data set. If 
OUTDATASET is specified, the entryname is 
dynamically allocated. For VSAM data sets, 
entryname can be that of a path. 

Abbreviation: ODS 

password 

specifies the update- or highei — level password 
for a password-protected output data set or path. 



Optional Parameters 



FROMKEY(key)|FROMADDRESSCaddress)| 

FROMNUMBER( number) iSKIPCcount.) ' 

specifies the location in the input data set from 
which copying is to start. You can use only one of the 
four possible choices. If no value is coded, the 
listing begins with the first logical record i n the 
data set. The only parameter that can be coded for a 
SAM data set is SKIP. None of these parameters can be 
specified if you are copying a catalog; the entire 
catalog must be copied. 



FROMKEY (key) 

specifies the key of the firs 
copied. You can specify gener 
keys shorter than that define 
If you specify generic keys, 
the first record whose key ma 
of the key you specified. (Yo 
key longer than that defined 
you do, the data set is not c 
specified key is not found, t 
is used as the starting point 



t record you want 
ic keys- — that is, 
d for the data set. 
copying begins at 
tches that portion 
u cannot specify a 
for the data set. If 
opi ed. ) If the 
he next higher key 
for copying. 



FROMKEY can be specified only when an alternate 
index, a key-sequenced VSAM data set, or an 
i ndexed-sequent i al (ISAM) nonVSAM data set is 
being copied. If FROMKEY is specified for the 
starting location, TOADDRESS cannot identify the 
ending location. 



key can contain 1 to 255 EBCDI 
must be enclosed in single quo 
contains commas, semicolons, b 
or slashes. A single quotation 
must be coded as two single qu 
the key is enclosed in single 
You can code key in hexadecima 
hexadecimal value is enclosed 
marks and preceded by an X— fo 
X f C2ClC8' . key can contain up 
characters. 



C characters, key 
tati on marks if i t 
lanks, parentheses, 
mark within a key 
otat i on marks i f 
quotation marks. 
1 form where the 
in single quotation 
r example > 
to 255 hexadecimal 
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Abbreviation: FKEY 

FROMADDRESS (address) 

specifies the relative byte address (RBA) of the 
first record you want copied. The RBA value must 
be the beginning of a logical record. If you 
specify this parameter for key-sequenced data, 
the records will be copied in physical sequential 
order instead of in logical sequential order. 
FROMADDRESS can be coded only for VSAM 
key-sequenced or entry-sequenced data sets or 
components. FROMADDRESS cannot be specified when 
the data set is being accessed through a path. 
FROMADDRESS cannot be specified for a 
key-sequenced data set with spanned records if 
any of those spanned records are to be accessed. 

Abbreviation: FADDR 

FROMNUMBERC number) 

specifies, for a relative-record cluster, the 
relative-record number of the first record you 
want copied. 

Abbreviation: FNUM 

SKIPtcount) 

specifies the number of logical records you want 
to skip before beginning to copy records. For 
example, if you want to copy beginning with 
record number 500, you specify SKIPC499). SKIP 
should not be specified when you access the data 
set through a path; the results are 
unpredi ctable. 

address, number, and count can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n') form; the 
expression cannot be longer than one fullword (eight 
decimal or hexadecimal numbers, or 32 binary numbers). 

REPLACE 1 NOREPLACE 

specifies whether a record in the source cluster (INFILE or 
INDATASET) is to replace a record in the target cluster 
(OUTFILE or OUTDATASET) when the source cluster is copied 
into the target cluster. When a key-sequenced cluster or 
relative-record cluster (that is, the source cluster) is 
copied, its records might have keys or relative-record 
numbers identical to the keys or relative-record numbers of 
data records in the target cluster. 

REPLACE cannot be used if the output data set is identified 
as a path through an alternate index, or if the output data 
set is a base cluster whose upgrade set includes an 
alternate index defined with the unique-key attribute. 

Since the catalog Reload function automatically performs a 
Replace function, REPLACEl NOREPLACE is ignored if the 
output data set is a VSAM catalog. 

When a key-sequenced cluster, other than a catalog, is 
copied and you specify 5 

• REPLACE, each source record whose key matches a target 
record' 5 key replaces the target record. Otherwise, the 
source record is inserted into its appropriate place in 
the target cluster. 

♦ NOREPLACE, target records aren't replaced by source 
records. Each source record whose key matches a target 
record's key is not inserted into the target data set 
and a "duplicate record" message is issued. 

When a relative-record cluster is copied and you specify* 
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• REPLACE, each source record whose relative-record 
number identifies a data record (rather than an empty 
slot) in the target cluster replaces the target data 
record. Otherwise, the source data record is inserted 
into the empty slot its relative-record number 

i dent i f i es. 

• NOREPLACE, target records aren't replaced by source 
records. Each source record whose relative-record 
number identifies a target data record instead of an 
empty slot is not inserted into the target data set and 
a "duplicate record" message is issued. 

Abbreviations: REP and NREP 

REUSE 1 NOREUSE 

specifies whether the output data set is to be opened as a 
reusable data set. This parameter is valid only for VSAM 
data sets. When REUSE is specified, the output data set, 
specified with OUTFILE or OUTDATASET, is open'ed as a 
reusable data set regardless of whether or not it was 
defined as REUSE (see the DEFINE CLUSTER command 
description). If the data set was defined as REUSE, its 
high-used relative byte address (RBA) is reset to zero 
(that is, the data set is effectively empty) and the 
operation proceeds. If REUSE is specified and the data set 
was originally defined with the NOREUSE option, the data 
set must be empty; otherwise, the REPRO command terminates 
with an error message. 

If the NOREUSE attribute is specified (either explicitly or 
by default) and OUTFILE or OUTDATASET identifies a nonempty 
data set, records ar& written at the end of an 
entry-sequenced data set. Processing of key-sequenced and 
relative-record data sets is controlled by the 
REPLACE/NOREPLACE option used. 

Abbreviations: rus and NRUS 

TOKEY(key) iTOADDRESSCaddress) | 

TONUHBERC number) I COUNKcount ) 

specifies the location in the data set being copied at 
which copying is to stop. You can use only one of the four 
choices. If no value is coded, the copying ends with the 
logical end of the data set or component. The only 
parameter that can be specified for a sequential data set 
is COUNT. None of these parameters can be specified if you 
are copying a catalog; the entire catalog must be copied. 
The location at which the copying is to end must follow the 
location at which it is to begin. 

TOKEY(key) 

specifies the key of the last record you want copied. 
You can specify generic keys — that is, keys shorter 
than that defined for the data set. If you specify 
generic keys, copying stops after the last record is 
copied whose key matches that portion of the key you 
specified. (You cannot specify a key longer than that 
defined for the data set. If you do, the data set is 
not copied.) If the specified key is not found, the 
next lower key is used as the stopping point for 
copying. 

TOKEY can be specified only when an alternate index, a 
key-sequenced VSAM data set, or an i ndexed-sequenti al 
(ISAM) nonVSAM data set is being copied. If 
FROMADDRESS was specified for the starting location, 
TOKEY cannot be specified for the ending location. 

key can contain 1 to 255 EBCDIC characters, 'key must 
be enclosed in single quotation marks if it contains 
commas, semicolons, blanks, parentheses, or slashes. A 
single quotation mark within a key must be coded as 
two single quotation marks if the key is enclosed in 
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single quotation marks. You can code key in 
hexadecimal form where the hexadecimal value is 
enclosed in single quotation marks and preceded by an 
X — for example, X'C2ClC8 ,f . key can contain up to 255 
hexadecimal characters. 

TOADDRESS(address) 

specifies the relative byte address (RBA) of the last 
record you want copied. Unlike FROMADDRESS, the RBA 
value does not need to be the beginning of a logical 
record. The entire record containing the specified RBA 
is copied. If you specify this parameter for a 
key-sequenced data set, the records will be copied in 
physical sequential order instead of in logical 
sequential order. 

TOADDRESS cannot be specified as the ending location 
if FROMKEY was specified as the starting address. 
TOADDRESS can be used only with VSAM key-sequenced or 
entry-sequenced data sets or components. TOADDRESS 
cannot be specified when the data set is accessed 
through a path. TOADDRESS cannot be specified for a 
key-sequenced data set with spanned records if any of 
those v spanned records are to be accessed. 

Abbreviation: TADDR 

TONUMBER(number) 

specifies the relative-record number of the last 
record you want copied. TONUMBER can be specified only 
when you copy a relative-record cluster. 

Abbreviation: TNUM 

COUNT (count) 

specifies the number of logical records you want 
copied. COUNT should not be specified when you access 
the data set through a path; the results are 
unpredictable. 

address, number, and count can be expressed in decimal (n), 
hexadecimal (X'n f ), or binary (B'n*) form; the expression 
cannot be longer than one fullword (eight decimal or 
hexadecimal numbers, or 32 binary numbers). 
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REPRO EXAMPLES 



Copy Records Into a VSAM cluster: Example 1 



In this example, records from an i ndexed-sequenti al data set, 
ISAMDSET, are copied into key-sequenced VSAM cluster, 
D40. EXAMPLE. KSDS1. 

//REPR01 JOB 

//JOBCAT DD DSNAME=D27UCAT2,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//INDSET1 DD DSNAME=ISAMDSET,DISP=OLD, 
// DCB=(DS0RG=IS,BUFN0=6) 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
REPRO - 

INFILECINDSET1) - 
OUTDATASETCD40.EXAMPLE.KSDS1) 
yx 

The job control language statements ar&' 

• JOBCAT DD, which makes a catalog available for this job : 
D27UCAT2. 

• INDSET1 DD, which describes the i ndexed-sequent ial data set, 
ISAMDSET, that contains the input records. The BUFNO 
parameter specifies the number of buffers assigned to the 
ISAM data set. This improves performance when the ISAM data 
set's records are accessed. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The REPRO command copies all records from the input data set, 
ISAMDSET, to the output data set, D40 . EXAMPLE. KSDS1 . Its 
parameters are'' 

• INFILE, which points to the INDSET1 DD statement. The 
INDSET1 DD statement identifies the source, or input, data 
set ' ISAMDSET. ISAMDSET is an i ndexed-sequent i al data set. 

• OUTDATASET, which identifies the key-sequenced VSAM cluster 
into which the input records are to be copied. This data set 
is dynamically allocated by Access Method Services. 
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Copy Records Into a VSAM Cluster: Example 2 



In this two-part example* data records are copied from the 
nonVSAM data set SEQ.D27V, a sequential data set, into a 
key-sequenced VSAM cluster, D40.MYDATA. Next, records are copied 
from the key-sequenced cluster, D40.MYDATA, into an 
entry-sequenced cluster, ENTRY. 

//REPR02 JOB ... 

//JOBCAT DD DSNAME=MYCAT,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 

//INPUT DD DSNAME=SEQ.D27V,DISP=SHR,DCB=(BUFN0=6) 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
REPRO - 

INFILE(INPUT) - 

OUTDATASETCD40.MYDATA) 
/* 

//STEP2 EXEC PGM=IDCAMS 

//INPUT DD DSNAME=D40.MYDATA,DISP=OLD 
//OUTPUT DD DSNAME=ENTRY,DISP=OLD 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
REPRO - 

INFILE(INPUT) - 

OUTFILE(OUTPUT) - 

FROMKEY(DEAN) - 

TOKEY(JOHNSON) 
/* 

STEP1* Access Method Services copies records from a sequential 
data set, SEQ.D27V, into a key-sequenced VSAM cluster, 
D40.MYDATA. STEPl's job control language statements are- 

• JOBCAT DD, which makes the catalog MYCAT available for this 
job. 

• INPUT DD, which identifies the sequential data set, 
SEQ.D27V, that contains the input records. 4 The BUFNO 
parameter specifies the number of buffers assigned to the 
sequential data set. This improves performance when the data 
set's records are accessed. 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

STEPl's REPRO command copies all records from the input data 
set, SEQ.D27V, to the output data set, D40.MYDATA. Its 
parameters are'- 

• INFILE, which points to the INPUT DD statement. The INPUT DD 
statement identifies the source, or input, data set. 

• OUTDATASET, which identifies the key-seqTienced cluster into 
which the input records are to be copied. The data set is 
dynamically allocated by Access Method Services. 

STEP2 : Access Method Services copies some of the records of the 
key-sequenced cluster D40.MYDATA into another entry-sequenced 
cluster, ENTRY. STEP2's job control language statements arQ°> 

• JOBCAT DD, which applies to this job step as well as to 
STEP1. 

• INPUT DD, which identifies the key-sequenced cluster, 
D40.MYDATA, that contains the input records. 

• OUTPUT DD, which identifies the entry-sequenced cluster, 
ENTRY, that the records are copied into. 
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• SYSPRINT DD> which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. ^ 

STEP2's REPRO command copies records from the input data set, 
D40.MYDATA, to the output data set, ENTRY. Only those records 
with key values from DEAN to, and including, JOHNSON are copied. 
The REPRO command's parameters are* 

• INFILE, which points to the INPUT DD statement. The INPUT DD 
statement identifies the source, or input, key-sequenced 
cluster. 

• OUTFILE, which points to the OUTPUT DD statement. The OUTPUT 
DD statement identifies the entry-sequenced cluster into 
which the input records are to be copied. 

• FROMKEY and TOKEY, which specify the lower and upper key 
boundari es. . Only those records with key values from DEAN to, 
and including, JOHNSON are copied. 

If ENTRY already contains records, VSAM merges the copied 
records with ENTRY'S records. A subsequent job step could resume 
copying the records into ENTRY, beginning with the records with 
key greater than JOHNSON. If you subsequently copied records 
with key values less than DEAN into ENTRY, VSAM merges them with 
ENTRY'S records. 



346 0S/VS2 Access Method Services 



REPRO 



Copy a Catalog: Example 3 



In this example, a catalog is copied to illustrate the 
copy-catalog procedure. 

//COPYCAT JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DEFINE USERCATALOG - 
(NAMECCOPYUCAT) - 

MASTERPW(UCATMPW) - 
UDATEPW(UCATUPW) - 
F0RC365) - 
V0LUMECVSER06) - 
CYLINDERSC100 10) ) - 
DATA - 

(CYLINDERSC20 10) ) - 
INDEX - 

(CYLINDERSUO) ) - 
CATALOG - 

CAMASTCAT/MRCATPU2) 
/x 

//STEP2 EXEC PGM=IDCAMS 
//STEPCAT DD DSNAME=COPYUCAT,DISP=OLD 
// DD DSNAME=MYCAT,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
REPRO - 

INDATASET(MYCAT) - 
OUTDATASETCCOPYUCAT/UCATMPW) 
EXPORT - 

MYCAT - 
DISCONNECT 
/x 

//STEP3 EXEC PGM=IDCAMS 
//STEPCAT DD DSNAME=COPYUCAT,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD ^ 

LISTCAT 
/x 

//STEP4 EXEC PGM=IDCAMS 
//STEPCAT DD DSNAME=COPYUCAT,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
DELETE - 

MYCAT - 
CLUSTER - 
PURGE - 

CATALOGCCOPYUCAT/UCATMPW) 
/x 

//STEP5 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
DEFINE ALIAS - 

(NAMECMYCAT) - 
RELATE(COPYUCAT) ) 
/x 

STEP1: A user catalog, COPYUCAT, is defined on volume VSER06. 
The catalog entries in MYCAT will be copied into COPYUCAT. 
STEPl's job control statement is- 

• SYSPRINT DD, which is required in all Access Method Services 
job steps. The SYSPRINT DD statement identifies the output 
device to which Access Method Services messages to the 
programmer are to be sent. 

The DEFINE USERCATALOG command defines the user catalog, 
COPYUCAT. Its parameters are: 

• NAME, which specifies the name of the new catalog, COPYUCAT. 
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• MASTERPW and UPDATEPW, which specify the master and update 
level passwords for the catalog. 

• FOR, which specifies that the catalog is to be retained for 
365 days. " 

• VOLUME, which specifies that the catalog is to reside on 
volume VSER06. 

• CYLINDERS, which specifies that the catalog's data space is 
initially to be 100 cylinders. When the data space is 
extended, it is to be extended in increments of 20 
cylinders. Part of the data space contains the catalog, 
COPYUCAT. The rest of the data space is available for 
suballocated VSAM clusters. 

• DATA(CYLINDERS) and INDEX(CYLINDERS) specify that the 
catalog itself is initially to occupy 30 cylinders. VSAM 
determines the proportion of space to allocator to the 
catalog's data and index components. When the catalog's data 
component is extended, it is to be extended in increments of 
10 cylinders. 

• CATALOG, which specifies that a user catalog connector entry 
is to be built and written into the AMASTCAT catalog. The 
user catalog connector entry points to COPYUCAT. 

STEP2 : Access Method Services copies the contents of MYCAT into 
COPYUCAT. STEP2's job control statements are: 

• STEPCAT DD, which makes two catalogs available for this job 
step: COPYUCAT and MYCAT. The DD statements that identify 
the catalogs btq concatenated. 

• SYSPRINT DD (see STEP1 above). 

The REPRO command copies all records from MYCAT into COPYUCAT. 
Access Method Services treats each catalog as a key-sequenced 
VSAM cluster and copies each catalog record. Consequently, the 
first thirteen catalog records of MYCAT, which describe MYCAT as 
a key-sequenced cluster, ar^ also copied into COPYUCAT. Entries 
from MYCAT are written into COPYUCAT beginning with catalog 
record 14 (that is, after the thirteen self-describing records 
of COPYUCAT). The REPRO command's parameters are- 

• INDATASET, which identifies the source, or input, data set: 
MYCAT. VSAM assumes that MYCAT is cataloged in either MYCAT 
or COPYUCAT. 

• OUTDATASET, which identifies the receiving data set: 
COPYUCAT. VSAM assumes that COPYUCAT is cataloged in eii»her 
COPYUCAT or MYCAT. 

The EXPORT command removes MYCAT 's user catalog connector entry 
from the master catalog. MYCAT 's cataloged objects ar& now not 
available to the system. (STEP5 builds an alias entry that 
relates MYCAT to COPYUCAT, making the cataloged objects 
available to the system again.) 

STEP3: Access Method Services lists the name of each entry in 
the new catalog, COPYUCAT. The STEPCAT DD statement identifies 
the catalog to be listed. 

LISTCAT cannot run in a job step where the catalog is empty when 
it is opened. To ensure that the LISTCAT correctly reflects the 
contents of the catalog, the LISTCAT was run as a separate job 
step. 

STEP4 ; Access Method Services removes the entries in COPYUCAT 
that describe MYCAT as a key-sequenced cluster. (See STEP2 
description above.) The DELETE command's parameters ar&'> 

• MYCAT, which identifies the object to be deleted. 
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• CLUSTER, which specifies that MYCAT is cataloged as a 
cluster in COPYUCAT. MYCAT's cluster, data, and index entry 
are removed from COPYUCAT. 

• PURGE, which specifies that MYCAT is to be deleted 
regardless of a specified retention period or date. 

• CATALOG, which specifies that MYCAT is cataloged in 
COPYUCAT. COPYUCAT' s master password, UCATMPW, is required 
to delete its catalog entries. 

STEP5: Access Method Services builds an alias entry that relates 
MYCAT to COPYUCAT. Because no CATALOG parameter or JOBCAT or 
STEPCAT DD statement identifies the catalog that is to contain 
the alias entry, VSAM assumes the entry is to be written into 
the master catalog. 

When MYCAT was defined, it was defined on volume VSER04. Its 
catalog entries describe VSAM objects on that volume. COPYUCAT 
is defined on volume VSER06. Because MYCAT was copied into 
COPYUCAT (and MYCAT no longer exists as a user catalog), 
COPYUCAT entries now describe VSAM objects on volumes VSER04 and 
VSER06. 



Unload a VSAM User Catalog: Example 4 



This example shows how a VSAM user catalog can be unloaded to 
tape using the catalog unload/reload feature of the REPRO 
command. 

//UNLOAD JOB 

//JOBCAT DD DSNAME=D27UCAT2,DISP=0LD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//CATIN DD DSNAME=D27UCAT2,DISP=0LD 
//CATOUT DD DSNAME=P0RTABLE.TAPE,LABEL=(1,SL), 
// DISP=NEW, UNIT=24 0-3, VOL =SER=TAPE01, 
// DCB=(DEN=3,RECFM=VB,LRECL=516,BLKSIZE=5164) 
//SYSIN DD * 
REPRO - 

INFILECCATIN/UCATMRPW) - 

OUTFILE(CATOUT) 
/* 

The job control language statements are- 

• JOBCAT DD, which is required, and which identifies and 
allocates the user catalog as the job catalog. 

• CATIN DD, which describes and allocates the user catalog, 
D27UCAT2, as a VSAM data set to be opened and used by the 
REPRO command as the source data set for the unload 
operat i on . 

• CATOUT DD, which describes and allocates a magnetic tape 
file to contain the copy of the catalog. The DCB parameters 
must be specified as shown. The BLKSIZE parameter can be any 
multiple of LRECL, plus 4, where the minimum LRECL=5C5. 

The REPRO command causes the VSAM user catalog D27UCAT2 to be 
unloaded (that is, copied) to a magnetic tape file. The REPRO 
command's parameters are'- 

• INFILE, which is required, and which identifies the user 
catalog as an input, or source, VSAM data set. The catalog's 
master password is required to open it as a data set. 

• OUTFILE, which is required, and which describes the magnetic 
tape file, or target data set that i s to contain the 
catalog's copy. 
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//RELOAD 


JOB 


//JOBCAT 


DD 


//STEP1 


EXEC 


//SYSPRINT 


DD 


//CATIN 


DD 



Reload an Unloaded VSAM User Catalog: Example 5 

This example shows how a VSAM user catalog can be reloaded from 
the backup copy created in the previous example using the 
catalog unload/reload feature of the REPRO command. 

DSNAME=D27UCAT2,DISP=0LD 
PGM=IDCAMS 
SYS0UT=A 

DSNAME=PORTABLE. TAPE, L ABEL =(1,SL), 
// DISP=OLD,UNIT=2400-3,VOL=SER=TAPE01,DCB=DEN=3 
//CATOUT DD DSNAME=D27UCAT2,DISP=0LD 
//SYSIN DD X 
REPRO - 

INFILE(CATIN) - 
OUTFILECCATOUT/UCATMRPW) 
/x 

The job control language statements ar&' 

• JOBCAT DD, which is required and which describes and 
allocates the user catalog to be reloaded. The JOBCAT 
statement specifies that D27UCAT2 is the job catalog. 

• CATIN DD, which describes and allocates the magnetic tape 
file that contains the unloaded copy of the catalog. Since a 
standard label tape is used, DCB parameters of record 
format, recordsize, and blocksize need not be specified. For 
a non-labeled tape, the same parameters as in the previous 
example must be specified. 

• CATOUT DD, which describes the user catalog as a VSAM data 
set to be opened and used by REPRO as the target data set 
for the reload operation. 

The REPRO command causes a VSAM user catalog to be reloaded from 
the backup copy created in the previous example. The REPRO 
command's parameters are : 

• INFILE, which is required, and which identifies the magnetic 
tape file that contains the unloaded,, or backup, copy of the 
user catalog. 

• OUTFILE, which is required and which identifies the user 
catalog as a VSAM data set to be opened for record 
processing. The master password allows opening the catalog 
as a data set. 
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RESETCAT 



The format of the RESETCAT command is 



RESETCAT 



CATALOG(catname[/password] Eb dname] ) 
{CRAFILESUdnamelEb ALL|b NONE]) 
[(dnamelCb ALJL I b NONE] )...]) | 
CRAVOLUMESU volserEb devtype]) 
[(volserEb devtype])...])} 
[IGNORE I NOJGNORf] 
EMASTERPWl password)] 
EWORKCAT(catnameE/password] )] 
EWORKFILECdnameE/passwordi )] 



RESETCAT may be abbreviated: RCAT 



RESETCAT PARAMETERS 



Required Parameters 



CATALOG(catnameE/password] Edname] ) 

identifies the catalog to be reset. The catalog specified 
by catname must have the RECOVERABLE attribute. Exclusive 
control of the catalog is required throughout the duration 
of the command; also, no VSAM data sets cataloged in the 
catalog may be open. The master catalog may not be reset 
while it is in use as a master catalog. 

password 

specifies the catalog's master password. If the 
catalog is password-protected, you must specify the 
master password of the catalog. 



dname 



specifies the name of the DD statement for the catalog 
being reset. If dname is not specified, the catalog 
will be dynamically allocated. It must also be 
specified in a JOBCAT or STEPCAT. 



Abbreviation: CAT 
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CRAVOLUMES( (volserEb devtype])...) 

specifies the volume serial numbers and corresponding 
device types of the volumes used in resetting the catalog. 
Each volume contains a catalog recovery area (CRA) which 
has a copy of the catalog records that describe the objects 
on the volume. The volume is allocated dynamically. 

devtype 

specifies the device type for the associated volser. 
If you do not specify devtype, the volume must be 
mounted and on a unit marked permanently resident or 
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reserved. If you specify a generic name for devtype, 
the volume need not be mounted. 

If a volume contains a mult i volume data set whose 
catalog entry is being reset> other volumes of that 
multi volume data set may be needed during the reset 
operation; if needed and not specified for reset, 
these volumes will be allocated dynamically. 
Dynamically allocated volumes assume the NONE 
attribute as described for the CRAFILES parameter. 

Abbreviation: CRAVOL 



Optional Parameters 



IGNORE I NOIGNORE 

specifies whether RESETCAT should continue processing and 
force the reset when certain errors are encountered. These 
errors may be : 

• I/O error in the catalog 

• I/O error in the CRA 

• The volume record or its extensions in the CRA are in 
error. 

When you specify IGNORE, the RESETCAT command will try to 
recover as much information as possible and reset the 
catalog's description of those data sets on the specified 
volumes. For example, if IGNORE is specified and an I/O 
error occurs while processing a record from a CRA, that 
record will be ignored. In the process, data sets that 
could not be recovered on a particular volume would be 
marked unusable on that volume, and the space that was 
assigned to them would be freed. NOIGNORE specifies that 
these errors result in immediate termination. 

Abbreviations: IGN and NIGN 

MASTERPW(password) 

specifies the master catalog's master password. The master 
catalog's master password is required when the master 
catalog is password protected. 

WORKCAT t catnameC/password] ) 

specifies the name of the catalog in which RESETCAT defines 
the WORKFILE. This catalog must not be the same as the 
catalog being reset. If the catalog is password-protected, 
the update- or highei — level password is required. The 
catalog must be specified in a JOBCAT or STEPCAT DD 
statement. If you do not specify the WORKCAT parameter, the 
catalog will be chosen using existing rules for "Order of 
Catalog Use: DEFINE" in the chapter "Creating and 
Cataloging Objects." Further constraints must be followed 
if you do not specify the WORKCAT parameter, that is, it 
must be the first DD statement in the JOBCAT or STEPCAT DD 
statement concatenation. However, if the work file catalog 
is the master catalog, then you must specify the WORKCAT 
parameter and it must be the last DD statement in the 
JOBCAT or STEPCAT DD statement concatenation. The resultant 
catalog must not be the same one being reset. 

Abbreviation: WCAT 

U0RKFILE(dnameC/password3 ) 

specifies the name of a DD statement that identifies a VSAM 
data set name and a list of volume serial numbers of 
volumes containing VSAM data spaces and units to be used by 
RESETCAT for a work file. These volumes must be owned by 
the catalog in which the work file is defined. This data 
set will be defined by RESETCAT and used as temporary 
storage while processing the command; it will be deleted at 
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the end of the command. The data set must not be already 
defined. Space requirements for the data set are noted in 
"WORKFILE Space Requirements." If you do not specify 
WORKFILE, IDCUT1 is used as a default dname. 

password 

If you desire, you may specify password, a password to 
be used by RESETCAT to password-protect the work file. 
Since the work file will contain a copy of the catalog 
records, it may contain security-sensitive 
information. The password you specify will become the 
work file's master password. You may specify the 
password only if dname is explicitly specified. 

Abbreviation: WFILE 
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RESETCAT EXAMPLES 



Resetting a catalog: Example 1 



//STEPCAT 


DD 


// 


DD 


//IDCUT1 


DD 


// 


Vi 


//CRAV0L1 


DD 


//CRAV0L2 


DD 


//DDCAT 


DD 


//SYSIN 


DD 



This example illustrates the use of RESETCAT to reset a catalog 
(USERCAT1), one of whose owned volumes (VSER01) has been 
restored. The other volume owned by USERCAT1 is VSER02. 

//RECOVER JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

DSN=USERCAT1,DISP=0LD 
DSN=AMASTCAT,DISP=OLD 
DSN=W0RKFILE,DISP=0LD, 
VOL=SER=231401,UNIT=2314,AMP='AMORG T 
DISP=OLD,VOL=SER=VSER01,UNIT=2314 
DISP=OLD,VOL=SER=VSER02,UNIT=2314 
DSN=USERCAT1,DISP=0LD 
K 
RESETCAT - 

CATA10GCUSERCAT1/MASTER DDCAT) - 
CRAFILESUCRAV0L1 ALL) (CRAV0L2 NONE)) - 
WORKCATCAMASTCAT/MCATMRPW) - 
MASTERPWCMCATMRPW) - 
IGNORE 
/x 

The job control language statements are: 

• STEPCAT DD, which makes the user catalog, USERCAT1, and the 
master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset and 
for the work file to be defined, respectively. Note that 
when the work file is to be defined in the master catalog, 
the master catalog must be last in the concatenation and the 
catalog name is supplied via the WORKCAT parameter. 

• IDCUT1 DD, which identifies the data set to be used for the 
work file. 

• CRAV0L1 DD, which identifies and allocates a volume whose 
catalog recovery area is to be used ro reset the catalog. 

• CRAV0L2 DD, which identifies and allocates a volume whose 
catalog recovery area may change as a result of resetting 
the catalog recovery area on volume VSER01. This volume is 
not reset in the catalog. 

• DDCAT DD, which allocates the catalog to be reset. 

The RESETCAT command causes catalog USERCAT1 to be reset from 
the catalog recovery area on VSER01. The RESETCAT command's 
parameters are! 

• CATALOG, which identifies the catalog to be reset. The 
master password of the catalog is required to update the 
catalog. The DD statement for the catalog is also 
identified. 

• CRAFILES, which specifies a list of DD statements which 
identify the volumes to be used to reset the catalog. ALL 
specifies that the catalog records in the CRA on the volume 
specified by the CRAV0L1 DD statement are to be reset (in 
the catalog). NONE allows the CRAV0L2 DD statement to be 
specified for a CRA volume which is not to be used for 
reset, but which may be needed as a result of the reset (for 
example, a mult i volume data set resides on a reset volume 
and on a non-reset volume). 
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WORKCAT, which specifies the name of the catalog in which to 
define the work file. WORKCAT must be specified if the work 
file is to be defined in the master catalog. 

IGNORE, which specifies that RESETCAT should force the reset 
of the catalog despite certain errors which may be 
encountered during the RESETCAT processing. 



Resetting a Catalog: Example 2 



This example illustrates the use of RESETCAT to reset a catalog 
(USERCAT1) after the volume (VSEROO) on which the catalog 
resides has been restored. The volumes owned by USERCAT1> 
VSER01, and VSER02 have been determined to be out of 
synchronisation with the catalog by running a LISTCRA with the 
COMPARE option for all volumes owned by USERCAT1. 

//RECOVER JOB ... 

//JOBCAT DD DSN=USERCAT2,DISP=0LD 
// DD DSN=USERCAT1,DISP=0LD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//WORKF DD DSN=W0RKFILE,DISP=0LD,UNIT=(2314,2), 
// VOL =SER=( 231401, 231402 > , AMP=» AMORG* 

//SYSIN DD * 
RESETCAT - 

CATALOG(USERCATl) - 

CRAVOLSCCVSEROl 2314KVSER02 2314)) - 

WORKFILECWORKF/WRKPSW) - 

NOIGNORE 
/* 

The job control language statements are' 

• JOBCAT DD, which makes the user catalogs USERCAT2 and 
USERCAT1 available for the job. These catalogs must be 
available for the workfile to be defined and for the catalog 
to be reset, respectively. 

• WORKF DD, which identifies the data set to be used for the 
work file. 

Note: All other required volumes will be dynamically 
allocated by RESETCAT. 

The RESETCAT command causes catalog USERCAT1 to be reset from 
the catalog recovery areas on VSER01 and VSER02. The RESETCAT 
parameters are- 

• CATALOG, which identifies the catalog to be reset. 

• CRAVOLS, which specifies a list of volumes and their device 
types to be used to reset the catalog. 

• WORKFILE, which specifies the DD statement for the work file 
and a password to be used as the work file's master 
password. 

• NOIGNORE, which specifies that RESETCAT should not force the 
reset of the catalog if certain errors are encountered. 
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Resetting a Catalog: Example 3 
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//DISC 
//STEP1 



JOB ... 

EXEC PGM=IDCAMS 



//SYSPRINT DD 



//STEPCAT 
//SYSIN 



DD 
DD 



SYS0UT=A 
DSN=USERCAT1,DISP=0LD 



EXPORT USERCAT1 DISCONNECT 

//STEP2 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//UCATDD DD VOL=SER=VSER03,UNIT=3330 ,DISP=0LD 
//CRAV0L1 DD VOL=SER=VSER01,UNIT=2314,DISP=OLD 
//CRAV0L2 DD VOL=SER=VSER02, UNIT=2314, DISP=0LD 
//SYSIN DD * 
DEFINE UCAT - 

(NAME (USERCAT1) FILE(UCATDD) VOUVSER03) - 

RECOVERABLE CYK20 1)) - 

DATA(CYL(10 1)) INDEX(CYL( 1 ) ) 

//STEP3 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//STEPCAT DD DSN=USERCAT1, DISP=0LD 
// DD DSN=AMASTCAT,DISP=OLD 
//IDCUT1 DD DSN=W0RKFILE,DISP=0LD,UNIT=2314, 
// VOL=SER=231401,AMP='AMORG' 
//SYSIN DD * 
RESETCAT - 

CATALOG(USERCATl) - 

WORKCAT(AMASTCAT) - 

CRAVOLS((VSER00 3330)(VSER01 2314MVSER02 2314)) 
/* 

STEPl: The user catalog, USERCAT1, is disconnected from the 
system by using the EXPORT command. 

STEP2: The user catalog, USERCAT1, is redefined on the volume 
VSER03. 

STEP3: The user catalog USERCAT1 is reset from the previous 
catalog's owned volumes. 

The job control language statements are: 

• STEPCAT DD, which makes the user catalog, USERCAT1, and the 
master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset, and 
for the work file to be defined, respectively. 

• IDCUT1 DD, which identifies the data set to be used for the 
work file. 

The RESETCAT command causes the redefined catalog USERCAT1 to be 
reset from the catalog recovery areas on volumes VSEROO, VSER01, 
and VSER02. The RESETCAT command's parameters are: 

• CATALOG, which identifies the catalog to be reset. 

• WORKCAT, which specifies the name of the catalog in which to 
define the workfile. WORKCAT must be specified if the work 
file is to be defined in the master catalog. 
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RESETCAT 

CRAVOLS> which specifies a list of volumes and their device 
types to be used to reset the catalog. 
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VERIFY 



The format of the VERIFY command is 



VERIFY 



{FILECdnameC/passwordl ) | 

DATASET(entrynameL/password] 3} 



VERIFY can be abbreviated: VFY 



VERIFY PARAMETERS 



Required Parameters 



FILE(dnameC/password3 ) 

dname specifies the name of a DD statement that identifies 
the cluster or component to be verified. 

password 

is the control or master password of a 
password-protected cluster or component or the master 
password of a password-protected catalog. 

DATASET(entryname[/password] ) 

specifies the name and password of the object to be 
verified. If DATASET is coded, the object is dynamically 
allocated. 

password 

is the control or master password of a 
password-protected object* or is the master password 
of the object's (password-protected) catalog. 

Abbreviation: DS 

Note: When sharing data sets between different processors, 
it is recommended that you run VERIFY as the first step of 
a jobstream to prevent job termination caused by an open 
ACB error code, if the other processor already has the data 
set open. 

When you verify a data set in create mode it is only valid 
for an ESDS defined with the RECOVERABLE attribute. 



358 0S/VS2 Access Method Services 



VERIFY 
VERIFY EXAMPLE 

Upgrading a Data Set's End-of-File Information: Example 1 

When a data set that was improperly closed (that is, closed as a 
result of system failure) is opened, the VSAM Open routines set 
a return code to indicate that the data set's cataloged 
information might not be accurate. The user can upgrade the EOD 
and EOKR information (so that it is accurate when the data set 
is next opened) by closing the data set 2 and issuing the VERIFY 
command : 

//VERIFY JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 

//FIXEOD EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 



LISTCAT 



ENTRIES(FAROUT) - 
ALL 



VERIFY DATASET(FAROUT) 

LISTCAT ENTRIES(FAROUT) 
ALL 



/x 



SYSPRINT i s a DD statement required in all Access Method 
Services job steps to describe the output data set. for messages. 

The first LISTCAT command lists the data set T s cataloged 
information, showing the data set's parameters as they were when 
the data set was last closed properly. 

-The VERIFY command updates the data set's cataloged information 
to show the data set's real EOD and EOKR values. 

The second LISTCAT command lists the data set's cataloged 
information again. This time, the EOD and EOKR information show 
the point at which processing stopped due to system failure. 
This information should help the user determine how much of the 
data was added correctly before the system failed. 

Note: VERIFY will only update the high-used RBA fields for the 
data set, and not any record counts. 

See "Appendix B: Interpreting LISTCAT Output Listings" for 
details on the order in which catalog records are to be listed 
and the meanings of the listed records. 



When the data set is opened (first OPEN after system failure), VSAM Open 
sets a "data set improperly closed" return code. When the data set is 
closed properly, VSAM Close resets the "data set improperly closed" 
indicator but does not upgrade erroneous catalog information that resulted 
from the system failure. Subsequently, when the data set is next opened, 
its EOD and EOKR information might still be erroneous (until VERIFY is 
issued to correct it), but VSAM Open sets the "data set opened correctly" 
return code. 
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CONTROLLING COMMAND EXECUTION 



This chapter describes* 

• IF-THEN-ELSE command sequence, which is used to control 
command execution on the basis of condition codes. 

• DO-END command sequence, which specifies more than one 
functional Access Method Services command and its 
parameters. 

• SET command, which is used to reset condition codes. 

• PARM command, which is used to specify diagnos^t i c-ai ds and 
pri nted-output options. 

These commands cannot be used when Access Method Services is 
being executed under TSO. 



CONDITION CODES 



The condition codes that are tested in the IF-THEN-ELSE command 
sequence are-' 

• 0, which indicates that the function was executed as 
directed and expected. Some informational messages may have 
been issued. 

• 4, which indicates that some problem was met in executing 
the complete function, but it was possible to continue. The 
continuation might not provide the user with exactly what is 
wanted, but no permanent harm will have been done by such 
continuation. A warning message was issued. An example of 
the kind of problem encountered is"« the system was unable 
to locate an entry in a LISTCAT command. _ 

• 8, which indicates that a requested function was completed, 
but major specifics were unavoidably bypassed. For example, 
an entry to be deleted or altered could not be found, in the 
catalog, or a duplicate name was found while an entry was 
being defined and the define action was terminated. 

• 12, which indicates that the requested function could not be 
performed. This condition code is set as a result of a 
logical error. A logical error condition exists when 
inconsistent parameters are specified, when a too small or 
too large value is specified for key length, recordsize, or 
bufforspace, or when required parameters are missing. More 
information on logical errors that occur during VSAM record 
processing is in the OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide . 

• 16, which indicates that a severe error occurred that caused 
the remainder of the command stream to be flushed. This 
condition code might be set as a result, for example, of the 
following? a system output data set cannot be opened (a 
SYSPRINT DD statement was missing, for example); an 
unrecoverable error occurred in a system data set? or Access 
Method Services encountered improper IF-THEN-ELSE command 
sequences. 

The condition codes that are tested in the IF-THEN-ELSE command 
sequence and that can be set by the SET command cannot be passed 
from one job step to the next. However, the final maximum 
condition code is passed to the OS/VS system when the Access 
Method Services processor returns control to the system. 
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IF-THEN-ELSE COMMAND SEQUENCE 



The IF-THEN-ELSE command sequence is used to control command 
execution. 

The format of the IF-THEN-ELSE command sequence is: 




{LASTCC|MAXCC}Cb]comparandCb]number 
THENCb commandl 

DO 

command set 

END3 
CELSECb commandl 

DO 

command set 

END]] 



where: 

IF 

specifies that one or more functional commands is to be 
executed based on a test of a condition code. The condition 
code is set by a SET command or is set to reflect the 
completion status of previous functional commands. 

LASTCC 

specifies that the condition code value that resulted from 
the immediately previous function command is to be compared 
as indicated by the comparand number to determine whether 
the THEN action is to be performed. See "Condition Codes" 
earlier in this chapter for the meaning of condition codes. 

MAXCC 

specifies that the maximum condition code value that has 
been established by any previous function command or by a 
SET command is to be compared as indicated by the comparand 
number to determine whether the THEN action i s to be , 
performed. See "Condition Codes" earlier in this chapter 
for the meaning of condition codes. 

comparand 

specifies the comparison to be made between the variable 
and the following number. This can be any of six possible 
comparisons: 

Equal, specified as '=' or 'EQ' 

Not equal, specified as '-=' or 'NE' 

Greater than, specified as f >' or 'GT' 

Less than, specified as '<' or "LT' 

Greater than or equal, specified as '>=* or 'GE T 

Less than or equal, specified as '<=' or *LE' 



number 

specifies the decimal integer that 
MAXCC or LASTCC. The number can be 
Values greater than 16 are reduced 
MAXCC are initialized to zero upon 
Services. See "Condition Codes" earlier 
the meaning of condition codes. 



is to be compared with 
up to ten digits long, 
to 16; both LASTCC and 
entry to Access Method 

in this chapter for 



THEN 



specifies that a single command or a group of commands 
(introduced by DO) are to be executed if the comparison was 
true. THEN can be followed by another IF command. 
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ELSE 

specifies that a single command or a group of commands 
(introduced by DO) is to be executed if the previous 
comparison is false. ELSE can be followed by another IF> 
command. 

When an IF command appears in a THEN or ELSE clause, it is 
called a nested IF command. The maximum level of nesting allowed 
is 10, starting with the first time you specify IF. 

Within a nest of IF commands, the innermost ELSE clause is 
associated with the innermost THEN clause, the next innermost 
ELSE clause with the next innermost THEN clause, and so on. (To 
say it another way, each ELSE is matched with the nearest 
preceding unmatched THEN.) Should there be an IF command that 
does not require an ELSE clause, follow the THEN clause with a 
null ELSE clause (ELSE), unless the nesting structure does not 
require one. 



DO-END Command Sequence 
DO 



NULL COMMANDS 



SET COMMAND 



END 



specifies that the group of commands that follow is to be 
treated as a single unit, that is, to be executed as a 
result of a single IF command. The set of commands is 
terminated by END. Commands following a DO must begin on a 
new line. 



specifies the end of a set of commands initiated by the 
nearest unended DO. END must be on a line by itself. 

Note : Continuation characters should not be used in the 
DO-END sequence, as they may be taken as a null command or 
cause unpredictable results. 



If THEN or ELSE is not followed by a continuation character or 
by a command in the same record, the THEN or ELSE results in no 
action. 

The null command supports an ELSE command that balances an 
IF-THEN-ELSE command sequence, and allows null THEN commands. 
The null command is, in essence, a THEN or ELSE command that is 
not followed by a command-continuation character. 

If you want to indicate a null ELSE command, specify: 

ELSE 

If you want to indicate a null THEN command, specify: 

IF ... THEN 
ELSE ... 

The null command is used to indicate that no action is to be 
taken if the IF clause is satisfied (a null THEN command) or if 
the IF clause is not satisfied (a null ELSE command). 



The SET command is used to change or reset a previously defined 
condition code. See "Condition Codes" earlier in this chapter 
for the meaning of condition codes. It is possible to terminate 
all processing simply by setting MAXCC or LASTCC to 16. 
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The format of the SET command iss 



SET 



{MAXCC | LASTCC} Cb]=[b] number 



SET 



specifies that a condition-code value is to be set. A SET 
command that follows a THEN or ELSE that is not. executed 
does not cause the value of LASTCC or MAXCC to be altered 



PARM COMMAND 



MAXCC 

specifies that the value to be reset is the maximum 

condition code set by a previous functional command. 

Setting MAXCC does not affect the value of LASTCC. 

LASTCC 

specifies that the value to be reset is the condition code 
set by the immediately previous functional command. 

number 

specifies the value to be assigned to MAXCC or LASTCC. The 

maximum value that can be assigned is 16; a greater value 

will be reduced to 16. If the value assigned to LASTCC is 

greater than the value of MAXCC, MAXCC is set equal to the 
higher value. 



The PARM command specifies processing options to be used during 
execution. These options remain in effect until changed by 
another PARM command. You can also specify these options in the 
PARM field of an EXEC statement (in the JCL). 

The format of the PARM command is* 



PARM 


CTESTC 




{[TRACE] 




CAREASCareai dCb areaid...]}] 




CFULL((dumpid[b countUb count233) 




C (dumpi d. ..)...])] | 




0FF>)3 




[GRAPHICS(CHAIN(chain)|TABLEtmname))] 




[MARGINSdeftmargin b ri ghtmargi n ) ] 



it 



where* 

TESTC 

{[TRACE] 

[AREASCareaidCb areaid...])] 

CFULLttdumpidCb countlCb count2]]) 
C (dumpi d. ..)...])] | 
OFF)) 
specifies the diagnostic aids to be used. Once the TEST 
option has been established, it remains in effect until 
is reset by another PARM command. The TRACE, AREAS, and 
FULL parameters may be used concurrently. 

TRACE 

specifies that trace tables ar& to be listed whenever 
the built-in dump points of the processor are 
encountered. 

AREASCareaidCb areaid...]) 

identifies modules that are to have selected variables 
dumped at their dump points. Each item in the areaid 
is a two-character area-identifier defined within the 
implementation. See 0S/VS2 Access Method Services 
Lo gi c for more information. 
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FULL( (dumpidCb countl[b count23 3 Kdumpi d. . . 3 . .. . 3 ) 

specifies that a region dump, as well as the trace 

tables and selected variables, are to be provided at 

the specified points, dumpid specifies the 

foui — character identifier of the dump point. See 

0S/VS2 Access Method Services Logic for more 

i nf ormati on .' 

countl 

is a decimal integer that specifies the number of 
times (default is 1) the program is to go through 
the dump point before beginning the dump listing. 

count2 

specifies a decimal integer which is the number 
of times (default is 1) through the dump-point 
that dumps are to be listed. 

If the FULL keyword is used, an AMSDUMP^DD statement 
must be provided. For example 5 



OFF 



//AMSDUMP DD SYS0UT=A 



specifies that testing is to stop. 



GRAPHICS(CHAIN(chain)|TABLE(mnamen 

specifies the print chain/train graphic character set or a 
special graphics table to be used in producing the output. 
Any character to be printed is translated to the bit 
pattern found in such a table at the position corresponding 
to its numeric value (0 through 255). If the print chain 
does not have a graphic for a byte's bit pattern, the table 
should specify a period as the output graphic. 

CHAIN ( AN i HN | FN | QN ! RN | SN | TN ) 

specifies the graphic character set of the print 
chains or trains you wish employed. PN is used by the 
processor unless explicitly directed to use another 
set of graphics. 

TABLE(mname) 

specifies the name of a user — supplied table. This 
256-byte table defines the graphics for each of the 
256 possible bit patterns. It must be stored as a 
module accessible through the LOAD macro (VS). 

MARGINSdef tmargi n b rightmargin) 

specifies that the margins of input records on which 
command statements are written are to be changed. The 
normal left and right margins ar& 2 and 72, respectively. 
If MARGINS is coded, all subsequent input records are 
scanned in accord with the new margins. This feature may be 
used in conjunction with the comment feature- 
respeci f i cati on of margins could be used to cause the /* 
and */ characters to be omitted from the scan and so cause 
comments to be treated as commands. 

lef tmargi n 

specifies the location of the left margin. 

rightmargin 

specifies the location of the right margin. The right 
margin value must be greater than the left margin 
value. 
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CONTROL COMMAND EXECUTION EXAMPLES 



The examples in the topics that follow show the use of the 
IF-THEN-ELSE command sequence, the SET command, and the PARM 
command. 



Control command Execution: Example 1 



In this example, nested IF commands are used to determine 
whether a REPRO, DELETE, • or PRINT command is to be executed. 

IF LASTCC > 4 - 

THEN IF MAXCC < 12 - 

THEN REPRO. . . 

ELSE DELETE. . . 
ELSE IF LASTCC = 4 - 

THEN 

ELSE PRINT. . . 

This example specifies that if the value of LASTCC is greater 
than 4, then the value of MAXCC is to be tested. If the value of 
MAXCC is less than 12, the REPRO command is executed, while if 
the value of MAXCC is 12 or greater, the DELETE command is 
executed instead. Again, if the value of LASTCC is 4 or less, 
LASTCC is tested for being exactly 4? no action is to be taken 
in this case. If, however, LASTCC is less than 4, the PRINT 
command is to be executed. 



Control Command Execution: Example 2 



In this example, nested IF commands are used to determine 
whether a REPRO or PRINT command is executed. 

IF LASTCC > 4 - 

THEN IF MAXCC < 12 - 

THEN REPRO . . . 

ELSE 
ELSE IF LASTCC = 4 - 

THEN PRINT . . . 

Should the first IF command determine that LASTCC is greater 
than 4, and the second IF command determine that MAXCC is 12 or 
greater, no functional command in the example is executed. The 
null ELSE command is employed here to specify that the next ELSE 
is to correspond to the first THEN. 



Control Command Execution: Example 3 



In this example, if the maximum condition code is zero, an entry 
from a catalog is listed and a data set is printed. 

IF MAXCC=0 THEN DO 

LISTCAT CATALOG ( AMASTCAT/MST27 ) ENT (MN01.0005) 

PRINT INFILE (AJK006) 

END 

ELSE .... 



Control Command Execution: Example 4 



If you want to list a catalog and print a data set if the last 
condition code is zero, but list its catalog entry before and 
after a VERIFY command if the last condition code is greater 
than zero, specify : 
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IF LASTCC = THEN DO 

LISTCAT 

PRINT INFILE (AJK006) 

END 

ELSE DO 

LISTCAT ENTRY (AJK006) ALL 
VERIFY FILE (AJKJCL6) 
LISTCAT ENTRY (AJK006) ALL 
END 



Control command Execution: Example 5 



If you want to set the last condition code established to 12> 
speci fy * 

SET LASTCC=12 



Control command Execution: Example 6 



If you want to replace the highest condition code established in 
processing so far with 8, specify** 

SET MAXCC=8 
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APPENDIX A. EXAMPLES OF JOBS USING ACCESS METHOD SERVICES COMMANDS 



This set of examples is meant to show the wide range of 
functions provided by Access Method Services. It is assumed that 
the VSAM system catalog that exists is recoverable and security 
protected at the update-, control- and mastei — password levels. 

EXAMPLE l: DEFINE A VSAM USER CATALOG 

In this example, a user catalog is defined. The catalog is 
password protected. The user catalog in this example is security 
protected and is not defined with the recoverable attribute. The 
catalog's data space is defined to be 15 cylinders. The space 
explicitly specified for the data and index component of the 
catalog is taken from the catalog's data space. Since the total 
data space for the data and index component is less than the 
total catalog data space, the remaining catalog data space is 
available for suballocati on . The volume VSER02 cannot be 
referenced by other VSAM catalogs since it now belongs to the 
catalog which it contains. 

//DEFCAT JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE USERCATALOG - 

(NAMECD27UCAT1) - 

MASTERPW(UCATMRPW) - 

UPDATEPW(UCATUPPW) - 

F0RC365) - 

CYLINDERSC15 5) - 

V0LUMESCVSERQ2) - 
DATAC - 

CYLINDERSC3 1) ) - 
INDEXC - 

CYLINDERSC1 ) ) - 
CATALOGCAMASTCAT/MCATUPPW) 



Explanation of Commands 



1. The USERCATALOG parameter is required and NAME specifies the 
user catalog being defined. 

2. The MASTERPW parameter specifies the master password for 
thi s catalog. 

3. The UPDATEPW parameter specifies the update password of this 
catalog. 

4. The FOR parameter specifies the retention period for this 
file — in this case, one ye.ar . 

5. The CYLINDERS parameter specifies the amount of space to be 
allocated to the catalog's data space. A space parameter is 
requi red. 

6. The VOLUMES parameter is required and specifies the volume 
containing this catalog. Access Method Services will 
dynamically allocate the catalog's volume; the volume should 
be mounted permanently RESIDENT or RESERVED to ensure 
successful dynamic allocation. 

7. The DATA parameter specifies the amount of space to be 
allocated to the catalog's data component. 
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8. The INDEX parameter specifies the amount of space to be 
allocated to the catalog's index component. VSAM adds 
together the amount of space specified via DATA and INDEX 
and determines the appropriate proportions for each 
component . 

9. The CATALOG parameter is required since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. 

EXAMPLE 2: DEFINE A VSAM USER CATALOG AND A VSAM DATA SPACE 

This example defines a user catalog by using the 
previously-defined user catalog, D27UCAT1, as a model. The 
second part of this example defines a VSAM data space on volume 
VSER04. Both volumes in this example become owned by the 
respective catalogs, D27UCAT2 and AMASTCAT; they cannot be 
referenced by any other VSAM catalogs. 

The third part of this example defines alias names for the user 
catalogs, D27UCAT1 and D27UCAT2. 

This example depends on the successful completion of the 
previous example for the user catalog, D27UCAT1. 

//DEFCAT2 JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE USERCATALOG - 

CNAMECD27UCAT2) - 

M0DELCD27UCAT1/UCATMRPW D27UCAT1) - 
VOLUMECVSER03) - 
CYLINDERC15 5)) - 
CATALOGCAMASTCAT/MCATUPPW) 

DEFINE SPACE - 

CVOLUMECVSER04) - 
CYLINDERSC10 1) ) - 
CATALOGCAMASTCAT/MCATUPPW) 

DEFINE ALIAS - 

CNAMECD40) - 
RELATECD27UCAT1)) - 
CATALOGCAMASTCAT/MCATUPPW) 

DEFINE ALIAS - 

CNAMECD50) - 
RELATECD27UCAT2)) - 
CATALOGCAMASTCAT/MCATUPPW) 
/x 

Explanation of Commands 

The first DEFINE command defines a user catalog on volume 
VSER03. The catalog's attributes are modeled from a 
previously-defined user catalog, D27UCAT1. The VOLUME and 
CYLINDERS parameters are required parameters, even through a 
model catalog is used. 

1. The USERCATALOG parameter is required and NAME specifies the 
name of the user catalog, D27UCAT2. 

2. The MODEL parameter names the object to be used as a model 
and its master password, D27UCAT1/UCATMRPW. The next field 
names the catalog that contains the model object's catalog 
entries. In this case, D27UCATl's self-describing entries 
describe the object model, D27UCAT1. 
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3. The VOLUME parameter is required and names the volume that 
is to contain the user catalog. Access Method Services will 
dynamically allocate the catalog's volume; the volume should 
be mounted permanently RESIDENT or RESERVED to ensure 
successful dynamic allocation. 

4. The CYLINDERS parameter specifies the primary and secondary 
allocation amounts (of cylinders) to be allocated to the 
catalog's data space. A space parameter specifying the total 
amount of space is required. The space is allocated to data 
and index components of the catalog in the same way as that 
of the model . 

5. The CATALOG parameter is required since the master catalog 
is password protected. It names the master catalog, 
AMASTCAT> and specifies its update password. When a 

user — catalog is defined, a user catalog connector entry is 
built and written into the VSAM master catalog. The 
usei — catalog connector entry enables the user catalog's 
volume to be located through the master catalog. 

The second DEFINE command defines a VSAM data space on volume 
VSER04 and establishes the volume's ownership by the master 
catalog, AMASTCAT. All subsequent VSAM objects created on volume 
VSER04 are required to be cataloged in the volume's catalog, 
AMASTCAT. 

1. The SPACE parameter is required. 

2. The VOLUME parameter is required and names the volume that 
is to contain the data space. Access Method Services will 
dynamically allocate the volume; the volume should be 
mounted permanently RESIDENT or RESERVED to ensure 
successful dynamic allocation. 

3. The CYLINDERS parameter specifies the primary and secondary 
allocation amounts of cylinders to be allocated to the data 
space. A space parameter is required. 

4. The CATALOG parameter identifies the master catalog, 
AMASTCAT, and supplies its update password. 

The defines of the alias names permit references to the 
respective user catalogs by the alias names. Alias names for 
VSAM catalogs also provide a way by which data set names can be 
used to direct the search for catalog information about data 
sets. Some of the following examples will show how data set 
naming conventions are used to simplify JCL specification of 
JOBCAT and STEPCAT DD statements. 

1. The ALIAS parameter is required and NAME specifies the alias 
name of the user catalog. 

2. The RELATE parameter specifies the catalog for which the 
alias is defined. 

3. The CATALOG parameter supplies the update password of the 
master catalog, AMASTCAT. 



EXAMPLE. 3: DEFINE VSAM DATA SETS 



This example defines four VSAM data sets : two key-sequenced data 
sets into the user catalog, D27UCAT1, a relative-record data set 
into the system catalog, and a reusable entry-sequenced data set 
into the user catalog, D27UCAT2. 

This example depends on the successful completion of Example 1 
for the user catalog. 
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//DEFVSAM JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD x 

DEFINE - 

CLUSTER ( - 

NAMECD40.MYDATA) - 

VOLUMESCVSER02) - 

RECORDSCIOOO 500) - 
DATAC - 

NAMECD40.KSDATA) - 

KEYSC15 0) - 

RECORDSIZEC250 250J - 

FREESPACEC20 10) - 

BUFFERSPACEC25000) ) - 
INDEXC - 

NAMECD40.KSINDEX) - 

IMBED ) - 
CATAL0GCD27UCAT1/UCATUPPW) 

DEFINE CLUSTER - 

CNAMECD40. EXAMPLE. KSDS1) - 
READPW(KSDIPSWD) - 
MODELCD40.MYDATA)) - 
DATAC - 

CNAMECD40. EXAMPLE. KSDS1. DATA) - 
UNIQUE - 

CYLINDERSC2 1) ) - 
INDEXC - 

CNAMECD4 0.EXAMPLE.KSDS1. INDEX) • 
UNIQUE - 

CYLINDERSC1 1) ) - 
CATAL0GCD27UCAT1/UCATUPPW) 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIESC - 

D<+0 . EXAMPLE. KSDS1/KSD1PSWD) 

ALL 

DEFINE CLUSTER - 

CNAMECEXAMPLE.RRDS1) - 
VOLUMESCVSER04) - 
TRACKSC10 5) - 
RECORDSIZEC100 100) - 
NUMBERED ) - 
CATALOGCAMASTCAT/MCATUPPW) 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIESC - 

EXAMPLE. RRDS1) - 
CLUSTER - 
ALL 

DEFINE CLUSTER - 

CNAMECD50. EXAMPLE. ESDS1) - 
MASTERPWCESD1MRPW) - 
UPDATEPWCESD1UPPW) - 
VOLUMESCVSER03) - 
SPANNED - 
REUSE - 
NONINDEXED - 
CYLINDERSC2 1) - 
RECORDSIZEC2500 3000) ) - 
CATAL0GCD27UCAT2/UCATMRPW) 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIESC - 

D50.EXAMPLE.ESDS1) - 
ALLOCATION 
/x 
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Explanation of Commands 



The first DEFINE command defines a key-sequenced data set on 
volume VSER02. The high-level name of the data set is the alias 
name of the catalog into which it is being defined. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. 

2. The VOLUMES parameter is required and specifies the volume 
containing the data set. 

3. The RECORDS parameter specifies the space to be allocated to 
the cluster. This is a required parameter. 

4. The DATA parameter is required when attributes are to be 
explicitly specified for the data component of the cluster. 
The NAME parameter specifies the name of the data component. 

5. The KEYS parameter specifies the key length and offset. 

6. The RECORDSIZE parameter specifies the average and maximum 
record sizes. 

7. The BUFFERSPACE parameter is specified for improved 
performance. 

8. The INDEX parameter is required when attributes are to be 
explicitly specified for the index component of the cluster. 
The NAME parameter specifies the name of the index 
component. 

9. The IMBED parameter specifies that the i ndex. sequence set is 
to be placed with the data component. 

10. The CATALOG parameter is required since the catalog is 
password protected. 

The second DEFINE command defines a unique key-sequenced data 
set on volume VSER04. The high-level name of the data set is the 
alias name of the catalog into which it is being defined. This 
example shows how data set attributes can be specified by 
modeling and direct specification. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. 

2. The READPW parameter specifies the read password of this 
cluster. Since no master password is defined, this password 
will be propagated up to the master level. Thus this cluster 
is security protected even though its model was not 
protected. 

3. The MODEL parameter specifies the name of the data set to be 
used as the model. 

4. The DATA parameter is required if attributes are to be 
specified for the data component. The NAME parameter 
specifies the name of the data component. If a name is not 
specif ied> a name is generated. 

5. The UNIQUE parameter specifies that this portion of the data 
set is the only one that occupies the data space allocated 
to it. 

6. The CYLINDERS parameter specifies the amount of space to be 
allocated to the cluster's data component. 

7. The INDEX parameter is required if attributes are to be 
specified for the index component. The NAME parameter 
specifies the name of the index component. If a name is not 
specified, a name is generated. 
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8. The UNIQUE parameter specifies that this portion of the data 
set is the only one that occupies the data space allocated 
to it. 

9. The CYLINDERS parameter specifies the amount of space to be 
allocated to the cluster's index component. 

10. The CATALOG parameter is required, since the user catalog is 
password protected. It specifies the name of the user 
catalog and its update password which is required to define 
into a protected catalog. 

If the define of the unique key-sequenced data set was 
successful, then the following LISTCAT command is executed. The 
high-level name of the data set will direct the LISTCAT to the 
appropriate user catalog. 

1. The ENTRIES and ALL parameters cause the entire catalog 
description of the data set just defined to be' listed. 

The third DEFINE command defines a suballocated relative-record 
data set into the VSAM data space on volume VSER04 which is 
owned by the master catalog. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. 

2. The VOLUMES parameter is required and specifies the volume 
containing this data set. Because the master catalog is 
recoverable, Access Method Services will dynamically 
allocate this volume to access the catalog recovery area for 
the data set. This requires that the volume be mounted 
permanently RESIDENT or RESERVED. 

3. The TRACKS parameter specifies the amount of space allocated 
to this data set. A space parameter is required. 

4. The RECORDSIZE parameter specifies the average and maximum 
record sizes which, in the case of a relative-record data 
set, must be equal. 

5. The NUMBERED parameter is required to specify that this is a 
relative-record data set. 

6. The CATALOG parameter is required since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required. to define 
into a protected catalog. 

If the define of the suballocated relative-record data set was 
successful, then the following LISTCAT command is executed. 

1. The ENTRIES, CLUSTER, and ALL parameters cause the entry 

just defined to be listed, limited, however, to the cluster 
entry (that is, the data component's entry is not listed). 

The fourth DEFINE command defines a suballocated entry-sequenced 
data set on volume VSER03. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. The high-level name of the data set 
is the alias name of the catalog into which it is being 
defined. 

2. The MASTERPW parameter specifies the master password of this 
cluster. 

3. The UPDATEPW parameter specifies the update password of this 
cluster. 

4. The VOLUMES parameter is required and specifies the volume 
containing this data set. 
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5. The SPANNED parameter specifies that records may span 
control interval boundaries. 

6. The REUSE parameter specifies that the data set can be 
reused, that is, reloaded without being deleted and 
redefined. 

7. The NONINDEXED parameter is required to override the default 
(INDEXED). 

8. The CYLINDERS parameter specifies the amount of space to be 
allocated to this data set. A space parameter is required. 

9. The RECORDSIZE parameter specifies the average and maximum 
record sizes. 

10. The CATALOG parameter specifies the name of the catalog into 
which the cluster is to be defined. The catalog's update or 
highei — level password is required. 

If the define of the suballocated entry-sequenced data set was 
successful, then the following LISTCAT command is executed. The 
high-level name of the data set will direct the LISTCAT to the 
appropriate catalog. 

1. The ENTRIES and ALLOCATION parameters cause the data set 
entry just defined to be listed, limited, however, to only 
volume and allocation information. 

EXAMPLE 4: DEFINE NONVSAM AND VSAM DATA SETS 

This example defines a nonVSAM data set into a user catalog, a 
VSAM key-sequenced data set into the system catalog, and a VSAM 
entry-sequenced data set into a user catalog. 
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//DEFVSM2 


JOB 


♦ • ♦ 


//JOBCAT 


DD 


DSN=D27UCAT2,DISP=SHR 


//STEP1 


EXEC 


PGM=IDCAMS 


//SYSPRINT 


DD 


SYS0UT=A 


//SYSIN 


DD 


* 



DEFINE NONVSAM - 

(NAMECEXAMPLE.NONVSAM1) - 
VOLUMESC231401) - 
DEVICETYPESC2314) ) - 
CATAL0GCD27UCAT1/UCATUPPW) 

IF LASTCC = - 
THEN - 
LISTCAT NONVSAM - 

ALL - 

CATAL0GCD27UCAT1) 

DEFINE CLUSTER - 

(NAMECEXAMPLE.KSDS2) ) - 
DATAC - 

NAMECEXAMPLE.KSDS2.DATA) - 

MASTERPWCDAT2MRPW) - 

UPDATEPWCDAT2UPPW) - 

READPWCDAT2RDPW) - 

RECORDSC500 100) - 

EXCEPTIONEXIT(DATEXIT) - 

ERASE - 

FREESPACEC20 10) - 

KEYSC6 4) - 

RECORDSIZEC80 100) - 

VOLUMESCVSER04) ) - 
INDEXC - 

NAMECEXAMPLE.KSDS2. INDEX) - 

MASTERPWCIND2MRPW) - 

UPDATEPWCIND2UPPW) - 

READPWCIND2RDPW) - 

RECORDSC300 300) - 

IMBED - 

VOLUMESCVSER04) ) - 
CATALOGCAMASTCAT/MCATUPPW) 

IF LASTCC = - 
THEN - 

LISTCAT DATA - 
ALL - 
ENTRIES( - 

EXAMPLE. KSDS2/DAT2MRPW) - 
CATALOG(AMASTCAT) 

DEFINE CLUSTER - 

(NAME(EXAMPLE.ESDS2) - 
VOLUMESCVSER03) - 
SPANNED - 
CYLINDERSC2 1) - 
NONINDEXED - 
REUSE - 

MASTERPW(ESD2MRPW) - 
C0NTR0LPWCESD2CTPW) - 
UPDATEPWCESD2UPPW) - 
READPW(ESD2RDPW)) - 
CATALOGCD27UCAT2/UCATMRPW) 

IF LASTCC = - 
THEN - 
DO - 
LISTCAT ENTRIESC - 

EXAMPLE. ESDS2/ESD2MRPW) 
ALL 
LISTCAT NAME - 

CATALOGCAMASTCAT/MCATMRPW) 
END 



/* 
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Explanation of Job Control Language Statements 

1. The JOBCAT DD statement describes the user catalog D27UCAT2 
as a job catalog. All references will be to this job catalog 
unless otherwise directed. 

Explanation of commands 

The f«i rst DEFINE command defines an existing nonVSAM data set 
into user catalog D27UCAT1. 

1. The NONVSAM parameter is required and NAME specifies the 
nonVSAM object being defined. 

2. The VOLUMES parameter is required and specifies the volume 
containing the data set. 

3. The DEVICETYPES parameter is required and specifies the 
device type of the volume. 

4. The CATALOG parameter specifying the name of the user 
catalog is required because** 

• A job catalog also appears in the job control language, 
so this parameter explicitly directs the define to the 
user catalog. 

• The catalog is protected and its update password is 
required for the define. 

If the definition of the nonVSAM entry was successful, then the 
following LISTCAT command is executed. 

1. The NONVSAM and ALL parameters cause all the nonVSAM entries 
cataloged in D27UCAT1 to be listed. 

2. The CATALOG parameter directs the LISTCAT to a specific user 
catalog. 

The second DEFINE command defines a key-sequenced data set into 
a VSAM data space owned by the master catalog. Note that 
attributes are specified at the data and index level rather than 
at the cluster level. Access Method Services will dynamically 
allocate the volume containing the catalog recovery area for the 
cluster, since the system catalog is recoverable. This requires 
that the volume containing the index component of the cluster be 
mounted permanently RESIDENT or RESERVED to ensure successful 
dynamic allocation. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. 

2. The DATA component is explicitly named via the NAME 
parameter. 

3. The MASTERPW, UPDATEPW, and READPW parameters specify the 
master, update, and read passwords, respectively, of this 
data component. 

4. The RECORDS parameter specifies the amount of space to be 
allocated to the data component. A space allocation 
parameter is required. 

5. The EXCEPTIONEXIT parameter specifies the name of the 
routine to be given control if an exception occurs while 
processing the data component. 

6. The ERASE parameter specifies that the data component is to 
be overwritten with binary zeros when it is deleted. 

7. The FREESPACE parameter specifies the percentage of space 
within control intervals and control areas, respectively, 
that is to remain free. 
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8. The KEYS parameter specifies the key length and offset. 

9. The RECORDSIZE parameter specifies the average and maximum 
record sizes. 

10. The VOLUMES parameter is required and specifies the volume 
containing this data component. 

11. The INDEX component is explicitly named via the NAME 
parameter. 

12. The MASTERPW, UPDATEPW, and READPW parameters specify the 
master, update, and read passwords, respectively, of this 
index component. 

13. The RECORDS parameter specifies the amount of space to be 
allocated to the index component. A space allocation 
parameter is required. 

14. The IMBED parameter specifies that the index sequence set is 
to be placed with the data component. 

15. The VOLUMES parameter i s required and specifies the volume 
containing this index component. 

16. The CATALOG parameter is required, since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. This parameter is also required 
because a DD statement for the job catalog (JOBCAT) appears 
in the job control language and this define must, therefore, 
be explicitly directed to the master catalog. 

If the definition of the key-sequenced data set was successful, 
then the following LISTCAT command is executed. 

1. The DATA, ALL, and ENTRIES parameters cause all of the 
information contained in the data component entry to be 
li sted. 

2. The CATALOG parameter directs the LISTCAT to the master 
catalog. 

The third DEFINE command defines an entry-sequenced data set. 

1. The CLUSTER parameter is required and NAME specifies the 
cluster being defined. 

2. The VOLUMES parameter specifies the volume (VSER03) which is 
to contain the data set being defined. 

3. The SPANNED parameter specifies that records may span 
control interval boundaries. 

4. The CYLINDERS parameter specifies the amount of space to be 
allocated to this data set. A space parameter is required. 

5. The NONINDEXED parameter is required to override the default 
(INDEXED). 

6. The REUSE parameter specifies that the data set can be 
reused, that is, reloaded without being deleted and 
redefined. 

7. The MASTERPW, CONTROLPW, UPDATEPW, and READPW parameters 
specify passwords different from the passwords specified for 
the data set being modeled. 

8. The CATALOG parameter is required, since the user catalog is 
password protected. 

If the define of the entry-sequenced data set was successful, 
then the following LISTCAT commands are executed. 
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1. The ENTRIES and ALL parameters of the first LISTCAT command 
cause all the cataloged information in the entry just 
defined to be listed. 

2. The NAME parameter of the second LISTCAT command causes only 
the names of the objects cataloged in the master catalog to 
be 1 i sted. 

3. The CATALOG parameter specifies the master password of the 
master catalog which allows access to all objects in the 
catalog and directs the LISTCAT to the master catalog. 



EXAMPLE 5: COPYING AND PRINTING 



This example shows various techniques which can be used to load 
and print data sets using the REPRO and PRINT commands. This 
example depends on the successful completion of Examples 3 and 4 
for the existence of VSAM data sets to load records into. This 
example also requires that various nonVSAM data sets exist, so 
that data records can be loaded into the VSAM data sets. 
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//COPYPRNT JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//* NONVSAM INDEXED-SEQUENTIAL DATA SET 

//INDSET1 DD DSNAME=D40.IF100,DISP=OLD,DCB=DSORG=IS, 

// VOL=SER=231401,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET (VARIABLE-LENGTH 

//* RECORDS) 

//INDSET2 DD DSNAME=D40 . SVB200 ,DISP=OLD, 

// VOl=SER=231401,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET (FIXED-LENGTH 

//* RECORDS) 

//INDSET3 DD DSNAME=D40 . SF100 ,DISP=OLD, 

// V0L=SER=231401,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET 

//INDSET4 DD DSNAME=EXAMPLE.NONVSAMl,DISP=OLD, 

// V0L=SER=231401,UNIT=2314 

//SYSIN DD * 

/* LOAD A VSAM KEY-SEQUENCED DATA SET */ 
/* FROM AN ISAM DATA SET */ 

REPRO INFILE(INDSETl) - 

OUTDATASET(D40.EXAMPLE.KSDS1/KSD1PSWD) 

IF MAXCC = - 
THEN - 

PRINT INDATASET(D40. EXAMPLE. KSDS1/KSD1PSWD) - 
FROMKEY(X'40F0F0F0F0F6') 

/* LOAD A VSAM ENTRY-SEQUENCED DATA SET FROM AN */ 
/* EXISTING VARIABLE UNBLOCKED SAM DATA SET */ 

REPRO INFILE(INDSET2) - 

OUTDATASET(D50.EXAMPLE.ESDS1/ESD1UPPW) - 
COUNK030) 

IF LASTCC = - 
THEN - 
PRINT INDATASET(D50. EXAMPLE. ESDS1) - 

FROMADDRESS(170) - 

HEX 

/* LOAD A VSAM RELATIVE-RECORD DATA SET FROM AN */ 
/* EXISTING SAM DATA SET x/ 

REPRO INFILE(INDSET3) - 

OUTDATASET(EXAMPLE.RRDSl) - 
SKIPUO) 

IF LASTCC = - 
THEN - 

PRINT INDATASET(EXAMPLE.RRDSl) - 
T0NUMBER(25) 

/* PRINT THE CONTENTS OF THE SAM DATA SET */ 

PRINT INFILE(INDSET3) - 
COUNT(20) - 
CHARACTER 

/* LOAD A VSAM KEY-SEQUENCED DATA SET */ 
/* FROM A NONVSAM DATA SET */ 

REPRO INFILE(INDSET4) - 

OUTDATASET( EXAMPLE. KSDS2) 

IF LASTCC = - 
THEN - 

PRINT INDATASET(EXAMPLE.KSDS2) - 
FROMKEY(AAAAJA) - 
TOKEY(AAAAJ9) 
/* 
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Explanation of Job Control Language statements 

1. The INDSET1 DD statement describes the ISAM data set which 
is to be copied into the VSAM data set D40 . EXAMPLE. KSDS1 . 

2. The INDSET2 DD statement describes the variable-length SAM 
data set which is to be copied into the VSAM data set 
D50. EXAMPLE. ESDS1. 

3. The INDSET3 DD statement describes the SAM data set which is 
to be copied into the VSAM data set EXAMPLE. RRDS1 . 

4 . The INDSET4 DD statement describes the SAM data set which is 
to be copied into the VSAM data set EXAMPLE. KSDS2. 

Explanation of Commands 

The first REPRO command causes a VSAM key-sequenced data set to 
be loaded from an ISAM data set. 

1. The INFILE parameter identifies the data set containing the 
source data. (Note: Either the INFILE or INDATASET is 
required). The dname of the DD statement for this data set 
must be identical to this name. 

2. The OUTDATASET parameter identifies the name of the data set 
to be loaded. (Note: Either the OUTFILE or OUTDATASET is 
required). The data set is dynamically allocated by Access 
Method Services. The catalog containing the da.ta set is 
located by its alias 'D40'. The update or higher password of 
the VSAM data set is required. 

If the REPRO operation was successfully executed, then the 
contents of the VSAM key-sequenced data set just loaded are 
printed. The format of the listing is DUMP, since the default is 
taken . 

1. The INDATASET parameter identifies the name of the data set 
to be printed. (Note: Either INFILE or INDATASET is 
required.) The data set is dynamically allocated by Access 
Method Services. The catalog containing the data set is 
located by its alias 'D40'. The update- or higher — level 
password of the VSAM data set is required. 

2. The FROMKEY parameter specifies that printing is to begin 
with the record whose key (high-order three bytes) is 
greater than or equal to 'b00006' (that is, the character 
equivalent of X' 40F0F0F0F0F6 ' ) . 

The second REPRO command causes a VSAM entry-sequenced data set 
to be loaded from an existing variable unblocked SAM data set. 

1. The INFILE parameter identifies the data set containing the 
source data. The dname of the DD statement for this data set 
must be identical to this name. 

2. The OUTDATASET parameter identifies the name of the data set 
to be loaded. The data set is dynamically allocated by 
Access Method Services. The catalog containing the data set 
is located by its alias "D40 1 . The update or higher password 
of the VSAM data set is required. 

3. The COUNT parameter specifies that the first 30 records of 
the SAM data set are to be loaded. 

If the REPRO operation was successfully executed, then the 
contents of the VSAM entry-sequenced data set just loaded ar& 
printed in hexadecimal format. 
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1. The INDATASET parameter identifies the name of the data set 
to be printed. The data set is dynamically allocated by 
Access Method Services. The catalog containing the data set 
is located by its alias 'D40'. Since the data set is not 
read protected, no password is required. 

2. The FROMADDRESS parameter specifies that the first record 
printed is that record whose relative byte address is 
exactly equal to 170. 

3. The HEX parameter specifies that the listing is to be in 
hexadecimal format. 

The third REPRO command causes a VSAM relative-record data set 
to be loaded from an existing fixed SAM data set. The 
relative-record data set can receive only fixed length records 
that equal its defined record length. 

1. The INFILE parameter identifies the data set containing the 
source data. The dname of the DD statement for this data set 
must be identical to this name. 

2. The OUTDATASET parameter identifies the name of the data set 
to be loaded. The data set i s* dynami cally allocated by 
Access Method Services. The data set is cataloged in the 
master catalog; therefore, no JOBCAT or STEPCAT DD statement 
i s requi red. 

3. The SKIP parameter specifies that the first 10 records of 
the SAM data set arQ to be bypassed. 

If the REPRO operation was successfully executed, then the 
contents of the VSAM relative-record data set just loaded are 
printed. 

1. The INDATASET parameter identifies the name of the data set 
to be printed. The data set is dynamically allocated by 
Access Method Services. The data set is cataloged in the 
master catalog; therefore, no JOBCAT or STEPCAT DD statement 
is required. Since the data set is not read protected, no 
password is required. 

2. The TONUMBER parameter limits the output to those relative 
records with relative-record number less than or equal to 
25. 

The PRINT command causes the contents of the SAM data set to be 
pri nted. 

1. The INFILE parameter identifies the data set to be printed. 
The dname of the DD statement for this data set must be 
identical to this name. 

2. The COUNT parameter specifies that only 20 records ar& to be 
printed. 

3. The CHARACTER parameter specifies that the listing is to be 
in character format. 

The last REPRO command causes a VSAM key-sequenced data set to 
be loaded from a nonVSAM data set. 

1. The INFILE parameter identifies the data set containing the 
source data. The dname of the DD statement for this data set 
must be identical to this name. 

2. The OUTDATASET parameter identifies the name of the data set 
to be loaded. The data set is dynamically allocated by 
Access Method Services. The data set is cataloged in the 
master catalog. Note that a password is not required since 
the cluster component is not password protected although its 
data and index components are. 
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If the REPRO operation was successfully executed* then the 
contents of the V5AM key-sequenced data set just loaded are 
printed. The FROMKEY and TOKEY parameters are used to limit the 
output to a specific range of keys. 

1. The INDATASET parameter identifies the name of the data set 
to be printed. The data set is dynamically allocated by 
Access Method Services. The data set is cataloged in the 
master catalog. No password is required, because the cluster 
component is not password protected. 

2. The FROMKEY and TOKEY parameters specify the keys at which 
printing is to begin and end, respectively. 



EXAMPLE 6: RECORD REPLACEMENT 

This example shows techniques for modifying the contents of VSAM 
data sets using the REPRO command. 

This example depends on the successful completion of Example 5 
for the existence of nonempty VSAM data sets. 

//REPLACE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//INDSET4 DD DSNAME=EXAMPLE.N0NVSAM2,DISP=0LD, 

// VOL=SER = 231<f01,UNIT = 2314 

//SYSIN DD * 

REPRO INFILECINDSET4) - 

0UTDATASETCEXAMPLE.KSDS2) - 
REPLACE 

IF LASTCC = - 
THEN - 
PRINT INDATASETCEXAMPLE.KSDS2) - 

FROMKEY(AAAAJA) - 

T0KEYCAAAAJ9) 

REPRO INDATASET(EXAMPLE.RRDSl) - 

OUTDATASETCD50. EXAMPLE. ESDS1/ESD1UPPW) - 
REUSE 

IF LASTCC = - 
THEN - 

PRINT INDATASET (D50 . EXAMPLE. ESDS1 ) 
/* 

Explanation of Job Control Language Statements 

1. The INDSET4 DD statement describes the nonVSAM data set to 
be copied into the VSAM data set EXAMPLE. KSDS2 . 



Explanation of Commands 



The first REPRO command causes records in the VSAM key-sequenced 
data set to be replaced with input from a nonVSAM data set. 

1. The INFILE parameter identifies the data set containing the 
source data. (Note: Either INFILE or INDATASET is required.) 
The dname of the DD statement for this data set must be 
identical to this name. 

2. The OUTDATASET parameter identifies the target data set. 
(Note: Either OUTFILE or OUTDATASET is required.) Access 
Method Services will dynamically allocate the data set. The 
data set is cataloged in the master catalog; therefore, no 
JOBCAT or STEPCAT DD statement is required. Since the 
cluster is not password protected, no password is required. 
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3. The REPLACE parameter causes a record in the output data set 
having the same key as a record in the input data set to be 
replaced. Records in the input data set whose key is not 
already contained in the output data set will be inserted in 
the output data set. 

If the REPRO operation was successfully executed, then the 
contents of the VSAM key-sequenced data set just changed are 
printed. 

1. The INDATASET parameter identifies the data set to be 
printed. (Note: Either INFILE or INDATASET is required.) 
Access Method Services will dynamically allocate the data 
set. The data set is cataloged in the master catalog; 
therefore, no JOBCAT or STEPCAT DD statement is required. 
Since the cluster is not password protected, no password is 
requi red. 

2. The FROMKEY and TOKEY parameters specify the keys at which 
printing is to begin and end, respectively. 

The second REPRO command causes the VSAM entry-sequenced data 
set to be loaded from the VSAM relative-record data set. 

1. The INDATASET parameter identifies the source data set. 
Access Method Services will dynamically allocate the data 
set. The data set is cataloged in the master catalog. Since 
the cluster is unprotected, no password is required. 

2. The OUTDATASET parameter identifies the target data set. 
Access Method Services will dynamically allocate the data 
set. The catalog containing the data set is located by its 
alias 'D50'. The update- or highei — level password is 
required to load the data set. 

3. The REUSE parameter specifies that any records already in 
the entry-sequenced data set output are to be overwritten 
since the entry-sequenced data set was defined with the 
REUSE attribute. 

If the REPRO operation was successfully executed, then the 
entire contents of the reloaded VSAM entry-sequenced data set 
are printed. 

• The INDATASET parameter identifies the data set to be 

printed. Access Method Services will dynamically allocate 
the data set. The catalog containing the data set is located 
by its alias 'D50'. Since no read password exists for this 
data set, no password is required. 

EXAMPLE 7: ALTER THE CATALOGED ATTRIBUTES OF VSAM DATA SETS 

This example shows how the cataloged attributes of two VSAM data 
sets are modified. Each ALTER command is followed by a LISTCAT 
command, which will execute only if its previous ALTER command 
completed successfully. The LISTCAT command prints the updated 
catalog entry. 

This example depends on the successful completion of Example 3, 
which defined the two VSAM data sets whose attributes are being 
altered. 
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//ALTER JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

ALTER - 

D40. EXAMPLE. KSDS1. DATA - 
FREESPACEQO 10) 

IF LASTCC = - 
THEN - 
LISTCAT - 

ENTRIESCD40. EXAMPLE. KSDS1 . DATA/KSD1PSWD) 
ALL 

ALTER - 

D50. EXAMPLE. ESDS1/ESD1MRPW - 
MASTERPW(ESDIPWMR) - 
CONTROLPW(ESDIPWCT) - 
UPDATEPW(ESDIPWUP) - 
READPW(ESDIPWRD) 

IF LASTCC = - 
THEN - 
LISTCAT - 

ENTRIES (D50.EXAMPLE.ESDS1/ESD1PWMR) - 
CLUSTER - 
ALL 
/* 



Explanation of Commands 



The first ALTER command shows how a data set's space management 
attributes are "tuned" for optimum performance. 

The data component, D40 . EXAMPLE. KSDS1 . DATA, of a key-sequenced 
VSAM data set, D40 . EXAMPLE. K5DS1 , was defined with 40% free 
space in both control intervals and control areas. Now that data 
records have been loaded into the data set, its free space 
attributes no longer appear to require 40% freespace. It is now 
desirable to have 10% free space in both control intervals and 
control areas. The catalog containing the component to be 
altered is located through its alias *D40', which is the 
high-level qualifier of the component name. 

• D40. EXAMPLE. KSDS1 .DATA names the entry whose attributes are 
to be altered with this command. No password is required 
since the data object is not password protected. 

• The FREESPACE parameter respecifies percentages of free 
space that apply to the data component. 

The ALTER command is followed by a modal command that examines 
the condition code set when the ALTER command completes. If the 
ALTER command completes successfully, the LISTCAT command that 
immediately follows it prints the changed catalog entry. 

• The ENTRIES and ALL parameters explicitly name the entry to 
be listed and specify that the entire entry is to be listed. 
Since all information about the data component is to be 
listed, some information in the associated cluster must be 
accessed; this requires the cluster's read password. 

The second ALTER command shows how a data-set's passwords can be 
modified. You could use the same technique to provide passwords 
for an existing VSAM object that does not have passwords. 

• D50 . EXAMPLE. ESDS1 names the entry whose attributes ar& to be 
altered with this command. The entry's master password, 
ESD1MRPW, is supplied to allow the command to alter the 
entry's passwords. The catalog containing the entry to be 
altered is located through its alias 'D50'. 
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• The MASTERPW, CONTROIPW, UPDATEPW, and READPW parameters 
respecify passwords for the data set. 

If the ALTER command was successful, the LISTCAT command lists 
all of the cluster entry. 

EXAMPLE 8: CREATING AN ALTERNATE INDEX AND ITS PATH 

This example defines an alternate index over a previously loaded 
VSAM key-sequenced base cluster, defines a path over the 
alternate index to provide a means for processing the base 
through the alternate index, and builds the alternate index. The 
alternate index, path, and base cluster must all be defined in 
the same catalog, in this case, the master catalog. Since the 
master catalog is recoverable, Access Method Services will 
dynamically allocate the volume containing the base cluster's 
index component in order to access its recovery area. 

This example depends on the successful completion of Examples 4, 
5, and 6 for the existence of the nonempty VSAM base cluster 
EXAMPLE. KSDS2. 

//MAKEAIX JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//IDCUT1 DD DSNAME=S0RT. WORK. ONE, DISP=0LD, 
// AMP='AM0RG' ,VOL=SER=VSER01,UNIT=2314 
//IDCUT2 DD DSNAME=S0RT. WORK. TWO, DISP=0LD, 
// AMP='AMORG',VOL = SER = VSER01,UNIT = 231<+ 
//SYSIN DD * 

DEFINE ALTERNATEINDEX - 

(NAME(EXAMPLE.AIX) - 
RELATECEXAMPLE.KSDS2) - 
MASTERPW(AIXMRPW) - 
UPDATEPW(AIXUPPW) - 
KEYSC3 0) - 
RECORDSIZEC40 50) - 
VOLUMESCVSER04) - 
CYLINDERSC2 1) - 
NONUNIQUEKEY - 
UPGRADE ) - 
CATALOGCAMASTCAT/MCATUPPW) 

DEFINE PATH - 

(NAME(EXAMPLE.PATH) - 
PATHENTRYCEXAMPLE.AIX/AIXMRPW) - 
READPW(PATHRDPW)) - 
CATALOGCAMASTCAT/MCATUPPW) 

BLDINDEX INDATASETCEXAMPLE.KSDS2) - 

OUTDATASETCEXAMPLE.AIX/AIXUPPW) - 
CATALOGCAMASTCAT/MCATMRPW) 

PRINT INDATASETC EXAMPLE. PATH/PATHRDPW) 
/x 

Explanation of Job Control Language statements 

• The IDCUT1 and IDCUT2 DD statements describe the dsnames and 
a volume containing VSAM data space to be made available to 
BLDINDEX for defining and using two sort work data sets in 
the event an external sort is performed. This data space 
will not be used by BLDINDEX if enough virtual storage is 
available to perform an internal sort. 
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Explanation of commands 



The first DEFINE command creates a VSAM alternate index over the 
base cluster EXAMPLE. KSDS2 . 

1. The NAME parameter is required and names the object being 
def i ned. 

2. The RELATE parameter is required and specifies the name of 
the base cluster over which the alternate index is defined. 

3. The MASTERPW and UPDATEPW parameters specify the master and 
update passwords, respecti vely, for the alternate index. 

4. The KEYS parameter specifies the length of the alternate key 
and its offset in the base cluster record. 

5. The RECORDSIZE parameter specifies the length of the 
alternate-index record. It must be large enough to contain 
the prime keys for all occurrences of any one alternate key 
since the alternate index is being defined with the 
NONUNIQUEKEY attribute. 

6. The VOLUMES parameter is required and specifies the volume 
containing the alternate index EXAMPLE. AIX. 

7. The CYLINDERS parameter specifies the amount of space to be 
allocated to the alternate index. A space parameter is 
requi red. 

8. The NONUNIQUEKEY parameter specifies that the base cluster 
can contain multiple occurrences of any one alternate key. 

9. The UPGRADE parameter specifies that the alternate index is 
to reflect all changes made to the base cluster records, for 
example, additions or deletions of base cluster records. 

10. The CATALOG parameter is required, since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. 

The second DEFINE command defines a path over the alternate 
index. After the alternate index has been built, opening with 
the path name will cause processing of the base cluster via the 
alternate index. 

1. The NAME parameter is required and names the object being 
def i ned. 

2. The PATHENTRY parameter is required and specifies the name 
of the alternate index over which the path is defined and 
its master password. 

3. The READPW parameter specifies a read password for the path; 
it will be propagated to master-password level. 

4. The CATALOG parameter is required, since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. 

The BLDINDEX command builds an alternate index. The assumption 
is made that enough virtual storage will be available to perform 
an internal sort. However, note that DD statements with the 
default dnames of IDCUT1 and IDCUT2 have been provided for two 
external sort work data sets in the event that the assumption is 
incorrect and an external sort must be performed. 

1. The INDATASET parameter identifies the base cluster. Access 
Method Services will dynamically allocate the base cluster. 
The base-cluster's cluster entry is not password protected 
even though its data and index components are. 
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The OUTDATASET parameter identifies the alternate index. 
Access Method Services will dynamically allocate the 
alternate index. The update-or higher-level password of the 
alternate index is required. 

The CATALOG parameter specifies the name of the master 
catalog. If it is necessary for BLDINDEX to use external 
sort work data sets, they will be defined in and deleted 
from the master catalog. The master password will permit 
these actions. 

The PRINT command causes the base cluster to be printed by 
means of the alternate key using the path defined to create 
this relationship. 

• The INDATASET parameter identifies the path object. 
Access Method Services will dynamically allocate the 
path. The read password of the path is required. 



EXAMPLE 9: EXPORTING VSAM DATA SETS 



This example shows various methods of exporting data sets to 
provide backup and portability. 

The example depends on the successful completion of previous 
examples for the existence of the various objects to be 
exported. 
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//EXPORT JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//RECEIVE DD DSNAME=PORTABLE.TAPEl , LABEL=( 1 , SL) , 

// UNIT=240 0-3, DISP=CNEW, PASS ),VOL=SER=TAPE01, 

// DCB=CDEN=3,BLKSIZE=6000) 

//SYSIN DD * 

EXPORT - 

D40. EXAMPLE. KSDS1/KSD1PSWD - 

PURGE - 

OUTFILECRECEIVE) 

//STEP2 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE.TAPE2, LABEL=C2, SL ) , 

// UNIT=240 0-3, DISP=( NEW, PASS ), VOL =SER=TAPE01, 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

D50. EXAMPLE. ESDS1/ESD1PWMR - 
OUTFILECRECEIVE) - 
TEMPORARY - 
INHIBITSOURCE - 
INHIBITTARGET 

//STEP3 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE. TAPE3, LABEL=(3, SL) , 

// DISP=C NEW, PASS ),VOL=SER=TAPE01,UNIT=240 0-3, 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

EXAMPLE. AIX/MCATMRPW - 
OUTFILECRECEIVE) 

//STEP4 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE. TAPE4, LABEL=C4, SL ) , 

// DISP=C NEW, PASS), VOL =SER=TAPE01 ,UNIT=240 0-3, 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

EXAMPLE. KSDS2/MCATMRPW - 
OUTFILECRECEIVE) 
/* 

Explanation of Job Control Language statements 

1. The RECEIVE DD statements describe the portable data sets. 
The record format CVBS) and logical record length are set by 
EXPORT. The blocksize is set by EXPORT as 2048 except where 
overridden as in STEP1. 

Explanation of commands 

The first EXPORT command causes a key-sequenced VSAM data set to 
be exported from a user catalog. When it has been exported to a 
magnetic tape file, the key-sequenced data set is deleted from 
the user catalog. 

Note : When an object is exported, the record format of its 
records on the portable file is "VBS," and the EXPORT process 
determines the appropriate record size. However, the RECEIVE DD 
statement specifies a blocksize (BLKSIZE=6000 ) to override the 
blocksize used by the EXPORT process C2048 bytes) and to improve 
performance. 
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1. D40. EXAMPLE. KSUS1 names the key-sequenced VSAM data set 
being exported. Its password, KSD1PSWD, is also supplied 
(when the data set was defined, its read password propagated 
upward and all passwords for the data set are KSD1PSWD) . 
Access Method Services will dynamically allocate the 
cluster. The catalog containing the cluster is located 
through its alias 'D40', which is the high-level qualifier 
of the cluster name. 

2. The PURGE parameter is required, because the data set was 
defined with a retention period of 365 days. The data set 
cannot be exported permanently (that is, deleted from the 
catalog after its copy is made in the portable file) unless 
the PURGE parameter is specified to override its cataloged 
retention period. 

3. The OUTFILE parameter names the DD statement that describes 
and allocates the first file on a magnetic tape reel. (Note: 
Either OUTFILE or OUTDATASET is required.) 

The second EXPORT command causes an entry-sequenced VSAM data 
set to be exported from a user catalog. When it has been 
exported to a magnetic tape file, the data set's entry in the 
user catalog is marked "temporary export" and "inhibit update," 
which prevents the data set from being modified in any way. The 
user's program can only read the data set's records. In 
addition, when the data set's copy on magnetic tape is imported 
into another system catalog, the data set's entry in the new, or 
"target," catalog is marked "inhibit update." 

1. D50. EXAMPLE. ESDS1 names the entry-sequenced data set being 
exported. Its master password, ESD1PWMR, is also supplied. 
(Example 7 shows how the data set's passwords were changed.) 
Access Method Services will dynamically allocate the 
cluster. The catalog containing the cluster is located 
through its alias 'D50', which is the high-level qualifier 
of the cluster name. 

2. The OUTFILE parameter names the DD statement that describes 
and allocates the second file on a magnetic tape reel. 

3. The TEMPORARY parameter specifies that the data set is not 
to be deleted from the catalog when it is exported. 

4. The INHIBITSOURCE parameter specifies that the data set that 
remains in the "source" catalog and system is not to be 
updated or modified. 

5. The INHIBITTARGET parameter specifies that the data set's 
exported copy is not to be updated or modified when it has 
been imported into the "target" catalog and system. 

The third and fourth EXPORT commands cause the alternate index 
and base cluster to be exported from the master catalog. Any 
paths defined over either object will be exported with their 
PATHENTRY object. Since the export is permanent, both the base 
cluster and alternate index will be deleted from the catalog. 
The alternate index must be exported first, because the delete 
of the base cluster will cause deletion of all objects defined 
over it. 

The third EXPORT command causes an alternate index to be 
exported from the master catalog. 

1. The name of the alternate index being exported is required. 
A master password is required for the deletion and to allow 
VSAM locates against both the alternate index and path to 
obtain the catalog information (including passwords) to be 
exported. The master password of the catalog covers all 
requirements. Access Method Services will dynamically 
allocate the alternate index; this will also provide access 
to the catalog recovery area. 
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2. The OUTFILE parameter names the DD statement that describes 
and allocates the third file on a magnetic tape reel. 

The fourth EXPORT command causes a base cluster to be exported 
from the master catalog. 

1. The name of the base cluster being exported is required. 
Since the cluster level is not protected> no password would 
be required for the deletion. However, a password is 
required for the VSAM locates against the data and index 
components to obtain the catalog information (including 
passwords) to be exported. Since only one password can be 
supplied, it must be that of the master catalog. Access 
Method Services will dynamically allocate the cluster; this 
will also provide access to the catalog recovery area. 

2. The OUTFILE parameter names the DD statement that describes 
and allocates the fourth file on a magnetic tape reel. 

EXAMPLE 10: IMPORTING VSAM DATA SETS 

This example shows various methods of importing data sets. 

This example depends on the successful completion of Example 9> 
which created a portable magnetic tape that contains a copy of 
each VSAM data set to be imported. 
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//IMPORT JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=P0RTABLE.TAPE4,LABEL=C4,SL), 

// DISP=( OLD, PASS), VOL =SER=TAPE01 ,UNIT=240 0-3, DCB=DEN=3 

//SYSIN DD X 

IMPORT - 

INFILE(SOURCE) - 
0UTDATASETCEXAMPLE.KSDS2) - 
CATALOGCAMASTCAT/MCATUPPW) -■ 

//STEP2 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=P0RTABLE.TAPE3,LABEL=C3,SL), 

// DISP=C OLD, PASS), VOL =SER=TAPE01,UNIT=240 0-3, DCB=DEN=3 

//SYSIN DD X 

IMPORT - 

INFILECSOURCE) - 
OUTDATASET(EXAMPLE.AIX) - 
CATALOGCAMASTCAT/MCATUPPW) 

//STEP3 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=P0RTABLE.TAPE2,LABEL=C2,SL), 

// UNIT=240 0-3, DISP=( OLD, PASS), VOL =SER=TAPE01, 

// DCB=CDEN=3,LRECL=3004) 

//RECEIVE DD DSN=D50 . EXAMPLE. ESDS1 ,DISP=OLD 

//SYSIN DD x 

IMPORT - 

INFILECSOURCE) - 
OUTFILECRECEIVE) - 
CATAL0GCD27UCAT2/UCATMRPW) 

//STEP4 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=P0RTABLE.TAPE1,LABEL=C1,SL), 

// UNIT=240 0-3, DISP= COLD, PASS), VOL =SER=TAPE01, 

// DCB=CDEN=3,LRECL=479,BLKSIZE=600Q) 

//SYSIN DD x 

IMPORT - 

INFILECSOURCE) - 
OUTDATASETCD50.EXAMNEW.KSDS1) - 
CATAL0GCD27UCAT2/UCATUPPW) - 
OBJECTSC - 

CD40. EXAMPLE. KSDS1 - 
VOLUMESCVSER03) - 
NEWNAMECD50.EXAMNEW.KSDS1) ) - 
CD40. EXAMPLE. KSDS1. DATA - 

NEWNAMECD50.EXAMNEW.KSDS1.DATA) ) - 
CD40. EXAMPLE. KSDS1. INDEX - 
NEWNAMECD50.EXAMNEW.KSDS1. INDEX) ) ) 
/x 



Explanation of Job control Language statements 



The SOURCE DD statements describe the portable data sets. 
For standard labeled tapes, the DCB parameters of LRECL and 
BLKSIZE need not be specified. However, the example shows 
parameters which would be required for a nonlabeled tape. 
Unless overridden by DCB parameters, the EXPORT command sets 
the blocksize to 2048 and the record length to blocksize 
minus 4. 

The RECEIVE DD statement in STEP3 describes and allocates 
D50. EXAMPLE. ESDS1, which was exported with the TEMPORARY 
attri bute. 
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Explanation of commands 

The first and second IMPORT commands will import the base 
cluster and alternate index exported in Example 9 into the 
master catalog. The importation causes each component to be 
newly defined. Since the alternate index cannot be defined until 
the base cluster has been defined, the base cluster must be 
imported first. The importation will cause any paths over the 
objects which were exported to be redefined. 

The first IMPORT command causes the base cluster to be imported 
into the master catalog. 

1. The INFILE parameter names the DD statement that describes 
and allocates the fourth file on the magnetic tape reel 
containing the portable data set. (Note* Either INFILE or 
INDATASET is required.) 

2. The OUTDATASET parameter identifies the data set being 
imported. (Note: Either OUTFILE or OUTDATASET is required.) 
Access Method Services dynamically allocates the data set 
after it has been defined; this will also provide access to 
the catalog recovery area. 

3. The CATALOG parameter is required, since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. 

The second IMPORT command causes an alternate index to be 
imported into the master catalog. 

1. The INFILE parameter names the DD statement that describes 
and allocates the third, file on the magnetic tape reel 
containing the portable data set. 

2. The OUTDATASET parameter identifies the data set being 
imported. Access Method Services dynamically allocates the 
alternate index after it has been defined; this will also 
provide access to the catalog recovery area. 

3. The CATALOG parameter is required, since the master catalog 
is password protected. It specifies the name of the master 
catalog and its update password which is required to define 
into a protected catalog. 

The third IMPORT command causes the previously-exported 
entry-sequenced VSAM data set to be imported. The data set is 
imported into the catalog from which it was exported. The 
portable data set (that is, the copy being imported) replaces 
the copy that exists in user catalog D27UCAT2. The IMPORT 
process searches user catalog D27UCAT2 (located through its 
alias 'D50') for the entry with an entryname of 
D50. EXAMPLE. ESDS1. It deletes that entry, then redefines a 
cluster entry using the catalog information obtained from the 
portable data set. Because the data set was exported with the 
TEMPORARY attribute (see the previous example), the IMPORT 
command doesn't need to supply volume information. 

Note : The SOURCE DD statement specifies a recordsise 
(LRECL=3004) because the largest record in the portable data set 
is 3000 bytes (that is, LRECL = (largest-record size) + 4). 
Otherwise, the default record size, blocksize minus 4> would be 
erroneously used by the EXPORT command. In the two previous 
steps, the default record size was used. 

1. The INFILE parameter names the DD statement that describes 
and allocates the third file on a magnetic tape reel. This 
is the portable data set to be imported. 

2. The OUTFILE parameter names the DD statement that describes 
and allocates the data set to be imported. Note that since 
the data set was exported with the TEMPORARY attribute, it 
exists in the catalog D27UCAT2 at step allocation time. 
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3. The CATALOG parameter is required, since the catalog is 
protected. It names the catalog that is to contain the 
imported data set. The catalog's master password is 
supplied, and allows the IMPORT process to delete the 
existing entry in the catalog and redefine a new entry for 
the entry-sequenced VSAM data set. 

The fourth IMPORT command causes the previously-exported 
key-sequenced VSAM data set, D40 . EXAMPLE. KSDS1, to be imported 
from its copy (that is, the first portable data set on the 
magnetic tape reel) to a different user catalog than it was 
exported from, D27UCAT2. The IMPORT command renames the *lata set 
and each of its components, as specified with the NEWNAME 
parameters, and specifies that the data set is to reside on a 
different volume than that from which it was exported. The 
high-level qualifier (D50) of the new component's name is the 
alias name of the user catalog, D27UCAT2. 

Note: The SOURCE DD statement describes the portabje data set 
created in STEP1 of the previous example. The blocksize 
parameter is included (even though it need not be, because the 
tape has a standard label and the information is contained in 
the data set header label) to illustrate the fact that the 
information specified when the data set is imported is required 
to be the same as was specified when the data set was exported. 
The LRECL parameter i s not required, because the maximum record 
size is 475 bytes and the default (blocksize minus 4) is 
adequate. However, by specifying a record size, the default is 
overridden and virtual storage is more efficiently used. When 
record size is specified, it is the largest-record size +4. 

1. The INFILE parameter names the DD statement that describes 
and allocates the portable data set containing the 
to-be-imported VSAM data set. 

2. The OUTDATASET parameter identifies the renamed data set. 
Access Method Services dynamically allocates the data set 
after it has been defined. 

3. The CATALOG parameter is required since the catalog is 
protected. It names the catalog that is to contain the 
imported data set's entry. The catalog's update password is 
supplied and allows the data set to be imported into the 
catalog. 

4. The OBJECTS parameter identifies the volume that is to 
contain the imported data set and specifies new names for 
each of the data set's components. The OBJECTS parameter 
identifies each entry of the imported data set with its 
original entryname, then specifies information that is to 
replace the information found in the portable data set's 
imported catalog entries, 

EXAMPLE 11: DELETING A VSAM CATALOG AND ITS CATALOGED OBJECTS 

This example deletes all entries defined in the previous 
examples and deletes the user catalogs which were defined. The 
result of this job is the removal of all data sets and catalogs 
defined in this set of examples. 
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//DELETE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

/* DELETE THE NONVSAM DATA SET EXAMPLE. NONVSAM1 */ 

DELETE EXAMPLE. NONVSAM1 - 
NOSCRATCH - 
NONVSAM - 
CATAL0GCD27UCAT1/UCATUPPW) 

/X DELETE VSAM DATA SETS CATALOGED IN */ 
/* USER CATALOGS D27UCAT1 AND D27UCAT2 */ 

DELETE (D50. EXAMPLE. ESDS1/ESD1PWMR - 
D50.EXAMNEW.KSDS1/KSD1PSWD - 
D40.MYDATA) - 
PURGE - 
CLUSTER 

/* DELETE THE ENTRY-SEQUENCED VSAM x/ 
/x DATA SET EXAMPLE. ESDS2 */ 

DELETE EXAMPLE. ESDS2/ESD2MRPW - 
PURGE - 
CATALOGCD27UCAT2) 

/* DELETE THE KEY-SEQUENCED VSAM */ 
/x CLUSTER EXAMPLE. KSDS2 x/ 

DELETE EXAMPLE. KSDS2 - 

CATALOGCAMASTCAT/MCATMRPW) 

/X DELETE THE RELATIVE-RECORD VSAM */ 
/X CLUSTER EXAMPLE. RRDS1 x/ 

DELETE EXAMPLE. RRDS1 - 
CLUSTER 

/* DELETE VSAM DATA SPACES FROM VOLUME x/ 
/x VSER04 AND, IF THE VOLUME DOESN'T */ 
/x CONTAIN VSAM OBJECTS, DELETE THE */ 
/X VOLUME'S ENTRY IN AMASTCAT X/ 

DELETE VSER04 - 

SPACE - 

CATALOGCAMASTCAT/MCATUPPW) 

/x DELETE THE VSAM USER CATALOG D27UCAT1 x/ 

DELETE D27UCAT1/UCATMRPW - 
USERCATALOG - 
PURGE 

/x DELETE THE VSAM USER CATALOG D27UCAT2 x/ 

DELETE D27UCAT2/UCATMRPW - 
USERCATALOG - 
PURGE 
/x 



Explanation of commands 



The first DELETE command deletes the nonVSAM data set named 
EXAMPLE. NONVSAM1. 

1. The name of the nonVSAM data set is required. 

2. The NOSCRATCH parameter specifies that the VTOC entry of the 
object being deleted is not to be removed. 
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3. The NONVSAM parameter ensures that the entry being deleted 
is a nonVSAM data set. 

4. The CATALOG parameter is required in this example to 
identify the catalog that describes the data set to be 
deleted. The catalog's update password is required to delete 
a nonVSAM data set. 

The second DELETE command deletes VSAM data sets cataloged in 
two user catalogs, D27UCAT1 and D27UCAT2. 

1. The names of the VSAM data sets are specified; in addition* 
the master passwords of two protected data sets are 
required. Since the high-level qualifier of the three data 
set names is the alias of the catalog that describes the 
data sets, the CATALOG parameter is not required to direct 
the catalog search. 

2. The PURGE parameter causes the entries to be deleted without 
regard for the retention period. 

3. The CLUSTER parameter ensures that the catalog object being 
deleted is a VSAM data set. 

The third DELETE command deletes the entry-sequenced VSAM data 
set EXAMPLE. ESDS2 from the user catalog, D27UCAT2. 

1. The name of the entry-sequenced data set, EXAMPLE. ESD2, and 
its master password, ESD2MRPW, are required to identify the 
object to be deleted. 

2. The PURGE parameter causes the entry to be deleted without 
regard to its retention period. 

3. The CATALOG parameter is required in this example to 
identify the catalog that describes the data set to be 
deleted. 

The fourth DELETE command deletes the key-sequenced VSAM data 
set EXAMPLE. KSDS2 from the master catalog. Because this data set 
is a base cluster, its related alternate index, EXAMPLE. AIX, and 
its path, EXAMPLE. PATH, are also automatically deleted from the 
master catalog. 

1. The name of the key-sequenced VSAM data set, EXAMPLE. KSDS2, 
is required to identify the object to be deleted. 

2. The CATALOG parameter is required, because the delete 
process will result in more than one protected object being 
deleted. It names the catalog that contains the catalog 
entry of each object to be deleted and supplies the 
catalog's master password, which allows each object in the 
catalog to be deleted. 

The fifth DELETE command deletes the relative-record VSAM data 
set EXAMPLE. RRDS1 from the master catalog. 

1. The name of the relative-record VSAM data set, 
EXAMPLE. RRDS1, is required to identify the object to be 
deleted. Because the data set was created without passwords, 
no password is required to delete it. 

2. The CLUSTER parameter specifies that a cluster is being 
deleted. 

The sixth DELETE command deletes each empty VSAM data space from 
volume VSER04. Because the volume no longer contains any VSAM 
objects, the DELETE command also removes the volume's entry from 
the master catalog and removes the master catalog's ownership of 
the volume. Access Method Services will dynamically allocate the 
volume, since the VTOC must be accessed. The volume should be 
mounted permanently RESIDENT or RESERVED to assure successful 
dynamic allocation. 
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Notes If VSAM data sets remain on a volume, the DELETE SPACE 
command only frees unused VSAM space on the volume. 

1. The name (that is, volume serial number) of the volume, 
V5ER04, is required to identify the object to be deleted. 

2. The SPACE parameter is required to specify that all data 
spaces on the volume are to be deleted and, if the volume 
does not contain VSAM objects, that the volume's entry is to 
be deleted from the catalog. 

3. The CATALOG parameter is required and names the catalog that 
owns the volume. The catalog's update password, MCATUPPW, 
allows the DELETE command to delete a volume entry or VSAM 
data space. 

The seventh DELETE command deletes the VSAM user catalog 
D27UCAT1. 

1. The name of the catalog and its master password &r& required 
to identify the object to be deleted. 

2. The USERCATALOG parameter is required to specify that a user 
catalog is being deleted. 

3. The PURGE parameter causes the entry to be deleted without 
regard to its retention period. 

The eighth DELETE command deletes the VSAM user catalog 
D27UCAT2. 

1. The name of the user catalog and its master password are 
requi red. 

2. The USERCATALOG parameter is required to specify that the 
object being deleted is a user catalog. 

3. The PURGE parameter causes the entry to be deleted without 
regard for the retention period. 
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APPENDIX B. INTERPRETING LISTCAT OUTPUT LISTINGS 



The various LISTCAT command options allow you to select the 
LISTCAT output that gives you the information you want. This 
appendix provides information on the structure of LISTCAT output 
when you specify certain options. It also lists and describes 
fields that can be printed for each type of catalog entry. 

Each listed entry is identified by its type (that is, cluster, 
nonVSAM, data, etc.) and by its entryname. Entries are listed in 
alphabetic order of the entrynames, except when the ENTRIES 
parameter is used. The entries are then listed in the order in 
which they are specified in the ENTRIES parameter. 

An entry which has associated entries is immediatfely followed by 
the listing of each associated entry, unless type options 
(CLUSTER, DATA, SPACE, etc.) have been specified or a generic 
entryname list was specified which excludes the associated 
entry. That is, a cluster's data component (and, if the cluster 
is key-sequenced, its index component) is listed immediately 
following the cluster. 

This appendix is organized in three parts? 

• "LISTCAT Output Keywords," which lists all field names that 
can be listed for each type of entry. 

• "Description of Keyword Fields," which describes each field 
name within a group of related field names. 

• "Examples of LISTCAT Output Listings," which describes and 
illustrates the LISTCAT output that results when various 
LISTCAT options are specified. 



LISTCAT OUTPUT KEYWORDS 

This section of the appendi x 1 i sts the field names associated 
with each type of catalog entry. Each field name is followed by 
an abbreviation that points to a group of related-field 
descriptions in the next section. Keywords are listed in 
alphabetic order, not in the order of appearance in the LISTCAT 
output . 

The group names and abbreviations are* 

Abbreviations Group Names 

ALC Allocation Group 

ASN Associations Group 

ATT Attributes Group 

DSP Data Space Group 

GDG Generation Data Group Base Entry, Special Fields 

for 

NVS NonVSAM Entry, Special Field for 

HIS History Group 
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Abbreviations Group Names 

PRT Protection Group 

STA Statistics Group 

VLS Volumes Group 

VOL Volume Entry, Special Fields for 



Alias Entry Keywords 



ASSOCIATIONS (ASN) 
entryname (HIS) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 



Alternate-Index Entry Keywords 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
CLUSTER (ASN) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT(HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
NOUPGRADE (ATT) 
PATH (ASN) 
PROTECTION (PRT) 
RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
UPGRADE (ATT) 
USAR (PRT) 
USVR (PRT) 



Cluster Entry Keywords 

AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
PATH (ASN) 
PROTECTION (PRT) 
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RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 



Data Entry Keywords 



ALLOCATION (ALC) 

AIX (ASN) 

ASSOCIATIONS (ASN) 

ATTEMPTS (PRT) 

ATTRIBUTES (ATT) 

AVGLRECL (ATT) 

AXRKP (ATT) 

BIND (ATT) 

BUFSPACE (ATT) 

BYTES/TRACK (VLS) 

CI/CA (ATT) 

CISIZE (ATT) 

CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 

CYLFAULT (ATT) 

DEVTYPE (VLS) 

DSTGWAIT (ATT) 

entryname (HIS) 

ERASE (ATT) 

EXCPEXIT (ATT) 

EXCP5 (STA) 

EXTENT-NUMBER (VLS) 

EXTENT-TYPE (VLS) 

EXTENTS (STA) 

EXTENTS (VLS) 
HIGH-CCHH (VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 

FREESPACE-%CI (STA) 

FREESPACE-JSCA (STA) 

FREESPC-BYTES (STA) 

HIGH-KEY (VLS) 

HI-KEY-RBA (VLS) 

HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

IMBED (ATT) 

INDEX (ASN) 

INH-UPDATE (ATT) 

INDEXED (ATT) 

KEYLEN (ATT) 

LOW-KEY (VLS) 

MASTERPW (PRT) 

MAXLRECL (ATT) 

MAXRECS (ATT) 

NOERASE (ATT) 

NOIMBED (ATT) 

NONINDEXED (ATT) 

NOREPLICAT (ATT) 

NOREUSE (ATT) 

NONSPANNED (ATT) 

NOSWAP (ATT) 

NOTRKOVFL (ATT) 

NONUNIQKEY (ATT) 

NOTUSABLE (ATT) 

NOWRITECHK (ATT) 

NUMBERED (ATT) 
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ORDERED (ATT) 
PGSPC (ASN) 
PHYRECS/TRK (VLS) 
PHYREC/SIZE (VLS) 
PROTECTION (PRT) 
RACF (PRT) 
HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
READPW (PRT) 
RECOVERY (ATT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
RECORDS/CI (ATT) 
REPLICATE (ATT) 
RKP (ATT) 
REUSE (ATT) 
RECVABLE (ATT) 
SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 
SPEED (ATT) 
SPLITS-CA (STA) 
SPLITS-CI (STA) 
SPANNED (ATT) 
STATISTICS (STA) 
SUBALLOC (ATT) 
SWAP (ATT) 

SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 
TRACKS/CA (VLS) 
TRKOVFL (ATT) 
UNORDERED (ATT) 
UNIQUE (ATT) 
UNIQUEKEY (ATT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
VOLFLAG (VLS) 
VOLSER (VLS) 
VOLUMES (VLS) 
WRITECHECK (ATT) 



Index Entry Keywords 



ALLOCATION (ALC) 
AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
AVGLRECL (ATT) 
BIND (ATT) 
BUFSPACE (ATT) 
CI/CA (ATT) 
CISIZE (ATT) 
CLUSTER (ASN) 
CODE (PRT) 
CONTROLPW (PRT) 
CYLFAULT (ATT) 
DEVTYPE (VLS) 
DSTGWAIT (ATT) 
entryname (HIS) 
ERASE (ATT) 
EXCPEXIT (ATT) 
EXTENTS (STA) 
EXTENT-NUMBER (VLS) 
EXTENT-TYPE (VLS) 
EXTENTS (VLS) 
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HIGH-CCHH (VLS) 

HIGH-RBA (VLS) 

LOW-CCHH (VLS) 

LOW-RBA (VLS) 

TRACKS (VLS) 
FREESPACE-%CI (STA) 
FREESPACE-%CA (STA) 
FREESPC-BYTES (STA) 
HIGH-KEY (VLS) 
HISTORY (HIS) 

CREATION (HIS) 

EXPIRATION (HIS) 

OWNER-IDENT (HIS) 

RCVY-CI (HIS) 

RCVY-DEVT (HIS) 

RCVY-VOL (HIS) 

RELEASE (HIS) 
IMBED (ATT) 
INDEX (STA) 

ENTRIES/SECT (STA) 

HI-LEVEL-RBA (STA) 

LEVELS (STA) 

SEQ-SET-RBA (STA) 
INH-UPDATE (ATT) 
KEYLEN (ATT) 
LOW-KEY (VLS) 
MASTERPW (PRT) 
MAXLRECL (ATT) 
NOERASE (ATT) 
NOIMBED (ATT) 
NOREPLICAT (ATT) 
NOREUSE (ATT) 
EXCPS (STA) 
EXTENTS (STA) 
NOTUSABLE (ATT) 
NOWRITECHK (ATT) 
ORDERED (ATT) 
PHYRECS/TRK (VLS) 
PHYREC-SIZE (VLS) 
PROTECTION (PRT) 
RACF (PRT) 
HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
RECOVERY (ATT) 
READPW (PRT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
REPLICATE (ATT) 
RKP (ATT) 
REUSE (ATT) 
SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 
SPEED (ATT) 
SPLITS-CA (STA) 
SPLITS-CI (STA) 
STATISTICS (STA) 
SUBALLOC (ATT) 
SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 
TRACKS/CA (VLS) 
UNORDERED (ATT) 
UNIQUE (ATT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
VOLFLAG (VLS) 
VOLSER (VLS) 
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VOLUME (VLS) 
WRITECHECK (ATT) 



Generation Data Group Base Entry Keywords 

ASSOCIATIONS (ASN) 

ATTRIBUTES (GDG) 
EMPTY (GDG) 
LIMIT (GDG) 
NOEMPTY (GDG) 
NOSCRATCH (GDG) 
SCRATCH (GDG) 

entryname (HIS) 

HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

NONVSAM (ASN) 



NonVSAM Entry Keywords 

ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPE(VLS) 
entryname (HIS) 
FSEQN (NVS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
VOLSER(VLS) 



Page Space Entry Keywords 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
PROTECTION (PRT) 
RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
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Path Entry Keywords 



AIX (ASN) 

ASSOCIATIONS (ASN) 

ATTEMPTS (PRT) 

ATTRIBUTES (ATT) 

CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 

DATA (ASN) 

entry/name (HIS) 

HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

INDEX (ASN) 

MASTERPW (PRT) 

NOUPDATE (ATT) 

PROTECTION (PRT) 

RACF (PRT) 

READPW (PRT) 

UPDATE (ATT) 

UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 



User catalog Entry Keywords 

ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPE(VLS) 
entryname (HIS) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
VOLFLAG (VLS) 
VOLSER (VLS) 



Volume Entry Keywords 

ATTRIBUTES (DSP) 
AUTOMATIC (DSP) 
EXPLICIT (DSP) 
MASTERCAT (DSP) 
SUBALLOC (DSP) 
UNIQUE (DSP) 
USERCAT (DSP) 
BYTES/TRK (VOL) 
CHARACTERISTICS (VOL) 
CYLS/VOL (VOL) 
DATASET-DIRECTORY (DSP) 
ATTRIBUTES (DSP) 
DSN (DSP) 
EXTENTS (DSP) 
DATASETS (DSP) 
DATASETS-ON-VOL (VOL) 
DATASPACE (DSP) 
DATASPCS-ON-VOL (VOL) 
DEVTYPE (VOL) 
EXTENT-DESCRIPTOR (DSP) 
BEG-CCHH (DSP) 
SPACE-MAP (DSP) 
TRACKS-TOTAL (DSP) 
TRACKS-USED (DSP) 
EXTENTS (DSP) 
FORMAT-1-DSCB (DSP) 
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CCHHR (DSP) 

TIMESTAMP (DSP) 
MAX-PHYREC-SZ (VOL) 
MAX-EXT/ALLOC (VOL) 
HISTORY (HIS) 

RCVY-CI (HIS) 

RCVY-DEVT (HIS) 

RCVY-VOL (HIS) 

RELEASE (HIS) 
SEC ALLOC (DSP) 
TRKS/CYL (VOL) 
TYPE (DSP) 

CYLINDER (DSP) 

TRACK (DSP) 
volume serial number (HIS) 
VOLUME-TIMESTAMP (VOL) 



DESCRIPTION OF KEYHQRD FIELDS 



This section of the appendix contains a description of each 
field name. The field names are in the following groups of 
related information^ 

Abbreviations Group Names 

ALC Allocation Group 

ASN Associations Group 

ATT Attributes Group 

DSP Data Space Group 

GDG Generation Data Group Base Entry* Special Fields 

for 

NVS NonVSAM Entry, Special Field for 

HIS History Group 

PRT Protection Group 

STA Statistics Group 

VLS Volumes Group 

VOL Volume Entry, Special Fields for 

Groups are in alphabetic order. Field names within each group 
are in alphabetic order, not the order of appearance in the 
li sted entry. 



ALC: ALLOCATION GROUP 



The fields in this group describe the space allocated to the 
data or index component defined by the entry. 

HI-ALLOC-RBA — The highest RBA (plus 1) available within 
allocated space to store data. 

HI-USED-RBA — The highest RBA (plus 1) within allocated space 
that actually contains data. 

SPACE-PRI — Gives the number of units (indicated under TYPE) 
of space allocated to the data or index component when the 
cluster (that is, its data or index component) was defined. 
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This amount of space is to be allocated whenever a data 
component (or key range within it, and its associated 
sequence set, if IMBED is an attribute of the cluster) is 
extended onto a candidate volume. 

SPACE-SEC — Gives the number of units (indicated under TYPE) 
of space to be allocated whenever a data set (or key range 
within it) is extended on the same volume. 

SPACE-TYPE — Indicates the unit of space allocation* 

CYLINDER — Cylinders 

TRACK — Tracks 



ASN: ASSOCIATIONS GROUP 



This group lists the type (cluster, data, etc.) and entry names 
of the objects associated with the present entry. A cluster or 
alternate index entry will indicate its associated path entries 
and data and index (if a key-sequenced data set) entries. 
Similarly, an index or data entry will indicate its associated 
cluster or the alternate index of which it is a component. 

• An a^ias entry points to: 

Its associated nonVSAM data set entry. 

A user catalog entry. (All alias entries for a nonVSAM 
data set entry are chained together, as are alias 
entries for a user catalog entry.) 

• An alternate-index entry points to* 

Its associated data and index entries. 
Its base cluster's cluster entry. 
Each associated path entry. 

• An alternate-index's data entry points to* 

Its associated alternate-index entry. 

• An alternate-index's index entry points to* 

Its associated alternate-index entry. 

• A cluster entry points to* 

Its associated data entry. 

Each associated path entry. 

For a key-sequenced cluster, its associated index entry. 

For a cluster with alternate indexes, each associated 
alternate index entry. 

• A cluster's data entry points to* 

Its associated cluster entry. 

• A cluster's index entry points to* 

Its associated cluster entry. 

• A generation data group base entry points to* 

Its associated nonVSAM data set entries. 

• A nonVSAM data set entry points to* 
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Its associated alias entry. 

Its associated generation data group (for a G0000V00 
nonVSAM) . 

• A page space entry points to* 

Its associated data entry. (The page space is cataloged 
as an entry-sequenced cluster with a cluster entry and 
an associated data entry.) 

• A path entry (that establishes the connection between a base 
cluster and an alternate index) points to* 

Its associated alternate index entry, and the alternate 
index's associated data and index entries. 

The data entry of its associated base cluster. 

For a key-sequenced base cluster, the index entry of its 
associated base cluster. 

• Path entry (that is an alias for a cluster entry) points to* 

Its associated base cluster entry. 

The data entry of its associated base cluster. 

For a key-sequenced cluster", the index entry of its 
associated base cluster. 

• A usei — catalog entry points to* 

Its associated alias entry. 
AIX — Identifies an alternate-index entry. 
ALIAS — Identifies an alias entry. 
CLUSTER — Identifies a cluster entry. 
DATA — Identifies a data entry. 

GDG — Identifies a generation data group (GDG) base entry. 
INDEX — Identifies an index entry. 
NONVSAM — Identifies a nonVSAM data set entry. 
PGSPC — Identifies a page space entry. 
PATH — Identifies a path entry. 
UCAT — Identifies a usei — catalog entry. 



ATT: ATTRIBUTES GROUP 



The fields in this group describe the miscellaneous attributes 
of the entry. See the DEFINE command for further discussion of 
most of these attributes. 

AVGLRECL — The average length of data records. AVGLRECL equals 
MAXLRECL when the records are fixed-length. 

AXRKP — Indicates, for an alternate index, the offset, from the 
beginning of the base-cluster's data record, at which the 
alternate-key field begins. 

BIND — The component is staged from mass storage to a 
direct-access storage staging drive when it is opened, and it is 
retained (bound) in direct-access storage until it is closed. 
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BUFSPACE — The minimum buffer space in virtual storage to be 
provided by a processing program. 

CI/CA — The number of control intervals per control area. 

CISIZE — The size of a control interval. 

CYLFAULT — The component i s not staged from mass storage to a 
direct-access storage staging drive when it is opened, but data 
from it is staged as the data is needed. 

DSTGWAIT — The component is destaged from direct-access storage 
to mass storage before VSAM returns control to the program that 
is closing it. 

ERASE — Records are to be erased (set to binary zeros) when 
deleted. 

EXCPEXIT — The name of the object's exception exit routine. 

IMBED — The sequence-set index record is stored along with its 
associated data control area. 

INH-UPDATE — The data component cannot be updated. Either the 
data component was exported with INHIBITSOURCE specified, or its 
entry was modified by way of ALTER, with INHIBIT specified. 

INDEXED — The data component has an index — it is key-sequenced. 

KEYLEN — The length of the key field in a data record. 

MAXLRECL — The maximum length of data or index records. AVGLRECL 
equals MAXLRECL when the records are fixed-length. 

MAXRECS — Identifies the highest possible valid relative-record 
number, for a relative-record data set. This value is calculated 
as follows? 

2 32 /CISIZE x number of records slots per control interval. 

NOERASE — Records are not to be erased (set to binary Os) when 
deleted. 

NOIMBED — The sequence-set index record is not stored along with 
its associated data control area. 

NONINDEXED — The data component has no index — it is 
entry- sequenced. 

NONSPAKNED — Data records cannot span control intervals. 

NONUNIQKEY — Indicates, for an alternate index, that more than 
one data record in the base cluster can contain the same 
alternate-key value. 

NOREPLICAT — Index records are not replicated. 

NOREUSE — The data set cannot be reused. 

NOSWAP — The page space is a conventional page space and cannot 
be used as a high speed swap data set. 

NOTRKOVFL — The physical blocks of a page space data set cannot 
span a track boundary. 

NOUPDATE— When the path is opened for processing, its associated 
base cluster is opened but the base cluster's upgrade set is not 
opened. 

NOUPGRADE — The alternate index is not upgraded unless it is 
opened and being used to access the base cluster's data records. 
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NOTUSABLE — The entry is not usable because (1) the catalog could 
not be correctly recovered by RESETCAT, or (2) a DELETE SPACE 
FORCE was issued for a volume(s) in the entry's volume list. 

NOWRITECHK — Write operations are not checked for correctness. 

NUMBERED — The cluster is a relative-record data set. 

ORDERED — Volumes are used for space allocation in the order they 
were specified when the cluster was defined. 

RECOVERY — A temporary CLOSE is issued as each control area of 
the data set is loaded, so the whole data set won't have to be 
reloaded if a serious error occurs during loading. 

RECORDS/CI — Specifies the number of records, or slots, in each 
control interval of a relative-record data set. 

RECVABLE — This attribute is set in the data entry of a 
recoverable catalog, and each of the catalog's volumes contains 
a catalog recovery area. 

REPLICATE — Index records are replicated (that is, each is 
duplicated around a track of the index's direct-access device). 

REUSE — The data set can be reused (that is, its contents are 
temporary and its high-used RBA can be reset to when it is 
opened) . 

RKP- — The relative key position — the displacement from the 
beginning of a data record to its key field. 

SHROPTNS — (n,m) The numbers n and m identify the types of 
sharing permitted. See SHAREOPTIONS in the DEFINE CLUSTER 
section for more details. 

SPANNED — Data records can be longer than control-interval 
length, and can cross, or span, control-interval boundaries. 

SPEED — CLOSE is not issued until the data set has been loaded. 

SUBALLOC — More than one VSAM cluster can share the data space. A 
VSAM catalog might also occupy the data space. 

SWAP — The page space is a high speed swap data set used by 
Auxiliary Storage Management during a swap operation to store 
and retrieve the set of LSQA pages owned by an address space. 

TEMP-EXP — The data component was temporarily exported. 

TRKOVFL — The physical blocks of a page space data set can span a 
track boundary. 

UNIQUE — Only one VSAM cluster or catalog can occupy the data 
space — the cluster or catalog is unique. 

UNIQUEKEY — Indicates, for an alternate index, that the 
alternate-key value identifies one, and only one, data record in 
the base cluster. 

UNORDERED — Volumes specified when the cluster was defined can be 
used for space allocation in any Order. 

UPDATE — When the path is opened, the upgrade set's alternate' 
indexes (associated with the path's base cluster) are also 
opened and are updated when the base cluster's contents change. 

UPGRADE — When the alternate index's base cluster is opened, the 
alternate index is also opened and will be updated to reflect 
any changes to the base cluster's contents. 

WRITECHECK — Write operations are checked for correctness. 
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DSP: DATA SPACE GROUP 



The fields in this group are included by LISTCAT, as part of a 
volume entry/ for each data space on the volume. If a volume 
contains no data spaces; it is a candidate volume. 

ATTRIBUTES — Describes the attributes of the data space. 

AUTOMATIC — The data space was created automatically by a 
secondary allocation operation. If a VSAM cluster must be 
given additional space on a volume and all existing data 
spaces are full, an existing data space will be extended, or 
a new one allocated on the volume, using catalog DADSM. A 
new data space so allocated is known as an implicit or 
automatic data space. 

EXPLICIT — The data space was created explicitly by a DEFINE 
MASTERCATALOG or USERCATALOG command, or a DEFINE 
ALTERNATEINDEX or DEFINE CLUSTER command with^the UNIQUE 
attribute specified or by a DEFINE SPACE command. 

MASTERCAT — The data space contains the master catalog. 

SUBALLOC — The data space might contain several VSAM 
clusters. 

USERCAT — The data space contains a user catalog. 

UNIQUE — The data space contains a single (unique) VSAM 
cluster or catalog. 

DATASET DIRECTORY — Lists the VSAM data sets that can be stored 
(see CANDIDATE below) or actually ar& stored (in whole or in 
part) in the data space. 

ATTRIBUTES — Describes the relation between the named data 
set and the data space. 

CANDIDATE — The volume is a candidate for storing the 
data set 

(NULL) — The data set is stored (in whole or in part) in 
the data space 

DSN — The data-set name of the object that can be stored or 
is stored on the volume. 

EXTENTS — The number of data set extents for the data set 
within the data space. 

DATASETS — The number of VSAM data sets stored (in whole or in 
part) in the data space. (The number includes data sets for 
which the volume is a candidate.) 

EXTENT-DESCRIPTOR — Describes the data space extent. 

BEG-CCHH — The device address (that is, CC = cylinder and HH 
= track) of the extent. 

SPACE-MAP — A hexadecimal number that tells what tracks are 
used and what tracks are free in the extent. The number 
consists of one or more RLCs (run length codes). The first 
RLC gives the number of contiguous used tracks, starting at 
the beginning of the extent; if all of the tracks in the 
extent are used, there is only one RLC. The second RLC gives 
the number of contiguous free tracks* beyond the used 
tracks. A third RLC gives used tracks again, a fourth gives 
free tracks, and so on. 

A 1-byte RLC gives the number of tracks less than 250; a 
3-byte RLC gives the number of tracks equal to or greater 
than 250. That is, if the first byte of an RLC is X'F9' 
(249) or less, it is the only byte of the RLC and gives the 
number of tracks. If the first byte of an RLC is X'FA' (250) 
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or more, the byte is followed by two more bytes that give 
the number of tracks (the first byte means nothing more than 
to look at the next two bytes). 

TRACKS-TOTAL — Allocated to the data space altogether. 

TRACKS-USED — Used to store data. 

EXTENTS — The number of data space extents in the data space. 

F0RMAT-1-DSCB — Identifies the format-1 DSCB that describes the 
data space. 

CCHHR — The device address (that is, CC = cylinder, HH = 
track, and R = record number) of the DSCB in the VTOC. 

TIMESTAMP — The time the data space was allocated (System/370 
time-of-day clock value). The DSCB contains the timestamp as 
part of the VSAM-generated name. 

SEC-ALLOC — Gives the number of units (indicated under TYPE) of 
space to be allocated whenever the data space is extended. 

TYPE — Indicates the unit of space allocation J 

CYLINDERS — Cyl i nders 

TRACK — Tracks 

GDG: GENERATION DATA GROUP BASE ENTRY, SPECIAL FIELDS FOR 

The special fields for a generation data group base entry 
describe attributes of the generation data group. 

ATTRIBUTES 

This field includes the following fields* 

EMPTY 

All generation data sets in the generation data group 
will be uncataloged when the maximum number (given 
under LIMIT) is reached and one more data set is to be 
added to the group. 

LIMIT 

The maximum number of generation data sets allowed in 
the generation data group. 

NOEMPTY 

Only the oldest generation data set in the generation 
data group will be uncataloged when the maximum number 
(given under LIMIT) is reached and one more data set 
is to be added to the group. 

NOSCRATCH 

Generation data sets are not to be scratched (see 
SCRATCH below) when uncataloged. 

SCRATCH 

Generation data sets &rB to be scratched (that is, the 
DSCB that describes each one is removed from the VTOC 
of the volume on which it resides) when uncataloged. 

NVS: NONVSAM ENTRY, SPECIAL FIELD FOR 

The special field for a nonVSAM data set describes a nonVSAM 
data set stored on magnetic tape. 

FSEQN — The sequence number (for the tape volume indicated under 
the "VOLUMES group" keyword VOLSER) of the file in which the 
nonVSAM data set is stored. 
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HIS: HISTORY GROUP 



The fields in this group identify the object's owner, identify 
its catalog recovery volume and release level, and give its 
creation and expiration dates. 

entryname — The name of the cataloged object. The entryname can 
be specified with the ENTRIES parameter of LISTCAT to identify a 
catalog entry. 

HISTORY — This field includes the following fields: 

CREATION — The Julian date (YY.DDD) on which the entry was 
created. This field will always contain 00.000 for a nonVSAM 
data set entry in an OS CVOL. 

EXPIRATION — The Julian date (YY.DDD) after which the entry 
can be deleted without specifying the PURGE parameter in the 
DELETE command. Julian date 99.999 indicates that PURGE is 
always required to delete the object. This field will always 
contain 00.000 for a nonVSAM data set entry in an OS CVOL. 

OWNER-IDENT — The identity of the owner of the object 
described by the entry. 

RCVY-CI — If the entry is in a recoverable catalog, this 
field contains the control interval number in the catalog 
recovery area where a duplicate of the entry can be found. 

RCVY-DEVT — If the entry is in a recoverable catalog, this 
field identifies the recovery-volume's device type. (See the 
Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 

RCVY-VOL — If the entry is in a recoverable catalog, this 
field contains the recovery-volume's serial number. 

RELEASE — The release of VSAM under which the entry was 
created (not the same as the release number of 0S/VS2) : 

1 = 0S/VS2 Releases 3 and releases previous to Release 3 

2 = 0S/VS2 Release 3.6 and any later releases 



PRT: PROTECTION GROUP 



The fields in this group describe how the alternate index, 
cluster, data component, index component, or path defined by the 
entry is password protected or RACF protected. NULL or 
SUPPRESSED might be listed under password protection and YES or 
NO might be listed under RACF protection. 

NULL indicates that the object defined by the entry has no 
passwords. 

SUPP indicates that the master password of neither the catalog 
nor the entry was specified, so authority to list protection 
information is not granted. 

RACF — Indicates whether or not the entry is protected by the 
RESOURCE Access Control Facility. 

YES — Entry is RACF protected. 

NO — Entry is not RACF protected. 

ATTEMPTS — Gives the number of times the console operator is 
allowed to attempt to enter a correct password. 

CODE — Gives the code used to tell the console operator what 
alternate index, catalog, cluster, path, data component, or 
index component requires him to enter a password. NULL is listed 
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under CODE if a code is not used — the object requiring the 
password is identified with its full name. 

CONTRQLPM — The control-interval password (that is, the password 
for control-interval access). NULL indicates no control-interval 
password. 

MASTERPW — The master password. 

READP14 — The read-only password. NULL indicates no read-only 
password. 

UPDATEPW — The update password. NULL indicates no update 
password. 

USAR — The contents (1 to 255 bytes, in character format) of the 
USAR (usei — security-authorization record). This is the 
information specified in the string subparameter of the AUTH 
subparameter of the DEFINE command. 

USVR — The name of the USVR (uset — security-verification routine) 
which is to be invoked to verify authorization of any access to 
the entry. 



STA: STATISTICS GROUP 



The fields in this group give numbers and percentages that tell 
how much activity has taken place in the processing of a data or 
index component. The statistics in the catalog are updated when 
the data set is closed. Therefore, if a failure occurs during 
CLOSE, the statistics may not be valid. Since a VSAM catalog 
remains open from job to job, its statistics are not updated. 

Statistic values can be any value from a minus to a large 
number, if a failure occurs before or during close processing. 
VERIFY does not correct these statistics. 

FREESPACE-5SCI — Percentage of space to be left free in a control 
interval for subsequent processing. 

FREESPACE-5JCA — Percentage of control intervals to be left free 
in a control area for subsequent processing. 

FREESPC-BYTE5 — Actual number of bytes of free space in the total 
amount of space allocated to the data or index component. Free 
space in partially used control intervals is not included in 
this statistic. 

INDEX — This field appears only in an index entry. The fields 
under it describe activity in the index component. 

ENTRIES/SECT — The number of entries in each section of 
entries in an index record. 

HI-LEVEL-RBA — The RBA (relative byte address) of the 
highest-level index record. 

LEVELS — The number of levels of records in the index. The 
number is if no records have been loaded into the 
key-sequenced data set to which the index belongs. 

SEQ-SET-RBA — The RBA (relative byte address), in decimal, of 
the first sequence-set record. The sequence set might be 
separated from the index set by some quantity of RBA space. 

The remaining fields in the Statistics group (except for the 
System Timestamp field), are updated only when the data set is 
closed. 

EXCPS — EXCP (execute channel program — SVC 0) macro instructions 
issued by VSAM against the data or index component. 
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EXTENTS — Extents in the data or index component. 

REC-DELETED— The number of records that have been deleted from 
the data or index component. Statistics for records deleted are 
not maintained when the data set is processed in control 
interval mode. 

REC-INSERTED — For a key-sequenced data set, the number of 
records that have been inserted into the data component before 
the last record; records originally loaded and records added to 
the end are not included in this statistic. For relative-record 
data sets, it i s the number of records inserted into available 
slots; the number of records originally loaded are included in 
this statistic. Statistics for records inserted are not 
maintained when the data set is processed in control interval 
mode. 

REC-RETRIEVED — The number of records that have been retrieved 
from the data or index component, whether for update or not for 
update. Statistics for records retrieved are not maintained when 
the data set is processed in control interval mode. 

REC-TOTAL — The total number of records actually in the data or 
index component. This statistic is not maintained when the data 
set is processed in control interval mode. 

REC-UPDATED — The number of records that have been retrieved for 
update and rewritten. This value does not reflect those records 
that were deleted, but a record that is updated and then deleted 
is counted in the update statistics. Statistics for records 
updated are not maintained when the data set is processed in 
control interval mode. 

SPLITS-CA — Control-area splits. Half the data records in a 
control area were written into a new control area and then were 
deleted from the old control area. 

SPLITS-CI — Control-interval splits. Half the data records in a 
control interval were written into a new control interval and 
then were deleted from the old control interval. 

SYSTEM-TIMESTAMP — The time (System/370 time-of-day clock value) 
the data or index component was last closed (after being opened 
for operations that might have changed its contents). 



VLS: VOLUMES GROUP 



The fields in this group identify the volume(s) on which a data 
component, index component, user catalog, or nonVSAM data set is 
stored. It also identifies candidate volume(s) for a data or 
index component. The fields describe the type of volume and 
give, for a data or index component, information about the space 
the object uses on the volume. 

• If an entry-sequenced or relative-record cluster's data 
component has more than one VOLUMES group, each group 
describes the extents that contain data records for the 
cluster on a specific volume. 

• If a key-sequenced cluster's data component has more than 
one VOLUMES group, each group describes the extents that 
contain data records for the cluster, or one of its key 
ranges, on a specific volume. 

• If a key-sequenced cluster's index component has more than 
one VOLUMES group, each group describes the extents that 
contain index records for the cluster, or one of its key 
ranges, on a specific volume. The first VOLUMES group 
describes the extent that contains the high-level index 
records (that is, index records in levels above the sequence 
set level). Each of the next groups describes th« extents 
that contain sequence-set index records for the cluster, or 
one of its key ranges, on a specific volume. The index 
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component of a key-sequenced data set with the IMBED 
attribute will have a minimum of two Volume Groups* one for 
the imbedded sequence set, and one for the high-level index. 
The extents for the imbedded sequence set will be the same 
as those for the data component. 

BYTES/TRACK — The number of bytes that VSAM can write on a track 
(listed for page spaces only). 

DEVTYPE — The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 

EXTENT-NUMBER — The number of extents allocated for the data or 
index component on the volume. 

EXTENT-TYPE — The type of extents: 

00 — The extents are contiguous. 

40 — The extents are not Preformatted. 

80 — A sequence set occupies a track adjacent to a control 
area . 

EXTENTS — Gives the pnysical and relative-byte addresses of each 
extent. 

HIGH-CCHH — The device address (that is, CC = cylinder and HH 
= track) of the end of the extent. 

HIGH-RBA — The RBA (relative byte address), in decimal, of 
the end of the extent. 

LOW-CCHH — The device address (that is, CC = cylinder and HH 
= track) of the beginning of the extent. 

LOW-RBA — The RBA (relative byte address), in decimal, of the 
beginning of the extent. 

TRACKS — The number of tracks in the extent, from low to high 
device addresses. 

HIGH-KEY 3 — For a key-sequenced data set with the KEYRANGE 

attribute, the highest hexadecimal value allowed on the volume 

in the key field of a record in the key range. A maximum of 64 
bytes can appear in HIGH-KEY. 

HI-KEY-RBA 3 — For a key-sequenced data set, the RBA (relative 
byte address), in decimal, of the control interval on the volume 
that contains the highest keyed record in the data s«t or key 
range. 

LOW-KEY 3 — For a key-sequenced data set with the KEYRANGE 
attribute, the lowest hexadecimal value allowed on the volume in 
the key field of a record in the key range. A maximum of 64 
bytes can appear in LOW-KEY. 

PHYRECS/TRK — The number of physical records (of the size 
indicated under PHYRECS-SIZE) that VSAM can write on a track on 
the volume. 

PHYREC-SIZE — The number of bytes that VSAM uses for a physical 
record in the data or index component. 

HI-ALLOC-RBA — The highest RBA (plus 1) available within 
allocated space to store data component, its key range, the 
index component, or the sequence set records of a key range. 



Multiple key ranges might reside on a single volume — the volumes group is 
repeated for each such key range field. 
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HI-USED-RBA — The highest RBA (plus 1) within allocated space 
that actually contains data component, its key range, the index 
component, or the sequence set records of a key range. 

TRACKS/CA — The number of tracks in a control area in the data 
component. (This value is computed when the entry is defined, 
and reflects the optimum size of the control area for the given 
device type and the nature of the entry — whether indexed, 
nonindexed, or numbered.) For a key-sequenced data set with the 
imbedded attribute, this value includes the sequence set track. 

VOLFLAG — Indicates whether the volume is a candidate volume or 
the first or a subsequent volume on which data in a given key 
range is stored. 

CANDIDATE — The volume is a candidate for storing the data or 
index component. 

OVERFLOW — The volume is an overflow volume on which data 
records in a key range are stored. The KEYRANGE begins on 
another (PRIME) volume. 

PRIME — The volume is the first volume on which data records 
in a key range are stored. 

VOLSER — The serial number of the volume. 



VOL: VOLUME ENTRY, SPECIAL FIELDS FOR 



The special fields for a volume entry describe the 
characteristics of the space that VSAM uses on the volume. 

volume serial number — The name of the cataloged volume entry. 
The volume serial number can be specified with the ENTRIES 
parameter of LISTCAT to identify the volume entry. 

BYTES/TRK — The number of bytes that VSAM can use on each track 
on the volume. 

CYLS/VOL — The number of cylinders that VSAM can use on the 
volume, including alternate track cylinders. 

DATASETS-ON-VOL- — The number of VSAM clusters that reside, in 

whole or in part, on the volume. Should the number of data 

spaces be zero, then this is a candidate volume only and this 
group is omitted. 

DATASPCS-ON-VOL — The number of VSAM data spaces on the volume. 
Should the number of data spaces be zero, then this is a 
candidate volume only, and the data space group is omitted. 

DEVTYPE — The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 

MAX-PHYREC-SZ — The size of the largest physical record that VSAM 
can write on the volume. 

MAX-EXT/ALLOC — The maximum number of extents that can be 
allocated per each allocation request for a single data set on 
the volume. 

TRKS/CYL — The number of tracks in each cylinder on the volume. 

VOLUME-TIMESTAMP — The time (System/370 time-of-day clock value) 
VSAM last changed the contents of the volume. The format-4 DSCB 
contains the timestamp at offset 76 (X*4C). 
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DEVICE TYPE TRANSLATE TABLE 

LISTCAT Code Device Type 

3000 8001 9 TRK TAPE 

3040 200A 3340 (35M/70M) 

3050 2006 2305-1 

3050 2007 2305-2 

3050 2009 3330 

3050 200B 3350 

3050 200D 3330-1 

3058 2009 3330V 

3080 8001 7 TRK TAPE 

30C0 2008 2314/2319 

3200 8003 9 TRK, 6250 BPI TAPE 

3400 8003 9 TRK, 1600 BPI TAPE 

Refer to 0S/VS2 System Programming Library' System 
Debugging Handbook, Volumes 1 and 2 for 
additional device types. 



EXAMPLES OF LISTCAT OUTPUT LISTINGS 

This section of the appendix illustrates the kind of output you 
can get when you specify LISTCAT parameters. It also describes 
the job control language you can specify and the output messages 
you get when the LISTCAT procedure executes successfully. 



JOB CONTROL LANGUAGE (JCL) FOR LISTCAT JOBS 



The job control language (JCL) statements that can be used to 
list a catalog's entries are* 

//LISTCAT JOB 
//STEP1 EXEC PGM=IDCAMS 
//STEPCAT DD DSN=YOURCAT,DISP=SHR 
//OUTDD DD DSN=LISTCAT. OUTPUT, UNIT=2400-3, 
// V0L=SER=TAPE1 0, L ABEL =( 1, NL ) , DISP=( NEW, KEEP), 

// DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 
//SYSPRINT DD SYS0UT=A 
//SYSIN . DD * 
LISTCAT - 

CATALOGCYOURCAT/PASSWORD) - 

OUTFILE(OUTDD) - 

/* 

The JOB statement contains user and accounting information 
required for your installation. 

The EXEC statement identifies the program to be executed, IDCAMS 
(that is, the Access Method Services program). 

• STEPCAT DD, which allocates your catalog. The catalog can be 
allocated dynamically if the STEPCAT and JOBCAT are omitted. 
If the catalog is dynamically allocated, its volume must be 
mounted as permanently RESIDENT or RESERVED. 

• OUTDD, which specifies an alternate output file, so that the 
LISTCAT output can be written onto an auxiliary storage 
device. The LISTCAT command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCAT output is written 
to the alternate output device. JCL statements, system 
messages, and job statistics are written to the SYSPRINT 
output device. 

DSN=LISTCAT. OUTPUT specifies the name for the magnetic 
tape file. 
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UNIT=2400-3 and VOL=SER=TAPE10 specifies that the file 
is to be contained on magnetic tape volume TAPE10. 

LABEL=( 1 ,NL ) specifies that this is the first file on a 
nonlabeled tape. You can also use a standard-labeled 
tape by specifying LABEL=( 1 ,SL ) . If subsequent job steps 
produce additional files of LISTCAT output on the same 
tape volume, you should increment the file number in 
each job step's LABEL subparameter (that is, 
LABEL=(2,NL) for the second job step, LABEL=C3,NL) for 
the third job step, etc.) 

DISP=(NEW,KEEP) specifies that this is a new tape file 
and is to be rewound when the job finishes. If a 
subsequent job step prints the tape, DISP=(NEW, PASS) 
should be specified. If your job step contains more than 
one LISTCAT command, DISP=(MOD,KEEP) or DISP=(M0D,PASS) 
can be used to concatenate all of the LISTCAT output in 
one sequential file. 

DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) specifies that the 
LISTCAT output records are variable-length, blocked 
5-to-l, and are preceded by an ANSI print-control 
character. 

• SYSPRINT DD, which is required for each Access Method 
Services job step. It identifies the output queue, SYS0UT=A, 
on which all LISTCAT output and system output messages are 
printed (unless the OUTFILE parameter and its associated DD 
statement is specified — see OUTDD above) . 

Note : If you want all output to be written to an auxiliary 
storage device, replace 'OUTDD' with 'SYSPRINT' in the OUTDD DD 
statement and omit the SYSPRINT DD SYS0UT=A statement. 

• SYSIN DD, which specifies, with an asterisk (*), that the 
statements that follow are the input data statements. A '/*' 
terminates the input data statements. 

The LISTCAT command parameters shown above are common to the 
LISTCAT examples that follow. Other LISTCAT parameters are coded 
with each example and the output that results is illustrated. 
These two parameters are optional * 

CATALOG, which identifies the catalog, YOURCAT, whose entries 
are to be listed. If the catalog is password protected, its read 
(or higher level) password, PASSWORD, is required. If the 
passwords and protection attributes of each entry are to be 
listed, the catalog's master password is required. 

OUTFILE, which points to the OUTDD DD statement. The OUTDD DD 
statement allocates an alternate output file for the LISTCAT 
output . 

$f you want to print the LISTCAT output that is contained on an 
alternate output file, you can use the IEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCAT. OUTPUT, that was allocated previously: 

//PRINTOUT JOB 

//STEP! EXEC PGM=IEBGENER 

//SYSUT1 DD DSN=LISTCAT. OUTPUT, UNIT=2400-3, . 

// VOL =SER=TAP El 0, LABEL =( 1 ,NL ) , DISP=( OLD, KEEP), 

// DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSUT2 DD SYS0UT=A 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD DUMMY 

/x 
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LISTCAT AND ACCESS METHOD SERVICES OUTPUT MESSAGES 

When the LISTCAT job completes* Access Method Services provides 
messages and diagnostic information. If an error occurred, an 
analysis of the error message can be found in OS/VS Message 
Library- VS2 System Messages . When your LISTCAT job completes 
successfully^ Access Method Services provides messages that 
follow the entry listing (see Figure 16): 



LISTING FROM CATALOG — MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GDG 1 

INDEX 3 

NONVSAM 2 

PAGESPACE 

PATH 1 

SPACE 1 

USERCATALOG 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE, MAXIMUM CONDITION CODE WAS 

Figure 16. Messages that Follow the Entry Listing 



The first line identifies the catalog that contained the listed 
entri es. 

The next group of lines specify the number of each entry-type> 

and the total number of entries, that were listed. This 

statistical information can help you determine the approximate 
size, in records, of your catalog. 

The next line specifies the number of entries that could not be 
listed because the appropriate password was not specified. 

The last two messages indicate that the LISTCAT command 
(FUNCTION) and the job step (IDCAMS) completed successfully. 
When LISTCAT is invoked from a TSO terminal, IDC0001I is not 
pri nted. 
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LISTCAT OUTPUT LISTING 



When you specify LISTCAT without any parameters* the entryname 
and type of each entry is listed (see Figure 17). The same 
listing would result if the NAMES parameter were specified. 

You can use this type of listing to list the name of each 
cataloged object and to determine the number of entries in the 
catalog. The total number of entries is an approximate size, in 
records, of your catalog. 
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/* LIST ENTRYNAMES OF THE CATALOG */ 
LISTCAT - 

CATALOG (MJKCAT) 



LISTING FROM CATALOG - 

AIX MJK.ALT.INDEX1 

DATA MJK. ALT. INDEX1. DATA 

INDEX MJK. ALT. INDEX1. INDEX 

PATH MJK. AIX1. PATH 

CLUSTER MJK.CLUSTER1 

DATA MJK. CLUSTER. DATA 

INDEX MJK. CLUSTER1. INDEX 

GDG BASE MJK.GDG1 

NONVSAM MJK.GDG1.G0001V00 

ALIAS MJK. GDG1. ALIAS 

NONVSAM MJK.NONVSAM1 

CLUSTER MJKCAT 

DATA VSAM. CATALOG. BASE. DATA. RECORD 

INDEX VSAM. CATALOG. BASE. INDEX. RECORD 

VOLUME 333001 



MJKCAT 



LISTING FROM CATALOG — MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GDG 1 

INDEX 3 

NONVSAM 2 

PAGESPACE 

PATH 1 

SPACE 1 

USERCATALOG 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 17. An Example of LISTCAT Output When No Parameters are Specified 
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LISTCAT VOLUME OUTPUT LISTING 



When the LISTCAT command is specified with the VOLUME parameter, 
the volume serial number and device type of each volume that 
contains part or all of the cataloged object are listed (see 
Fi gure 18) . 



/* LIST VOLUMES FOR EACH ENTRY */ 
LISTCAT - 

VOLUME - 
CATALOG (MJKCAT) 



LISTING FROM CATALOG 



MJKCAT 



AIX MJK.ALT.INDEX1 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

DATA MJK. ALT. INDEX1. DATA 

HISTORY 

OWNER-IDENT- (NULL) 

RELEASE 2 

VOLUMES 

VOLSER 333001 

INDEX MJK. ALT. INDEX!. INOEX 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

VOLUMES 

VOLSER 333001 

PATH MJK. AIX1. PATH 

HISTORY 

OWNER-IDENT (NULL ) 

RELEASE 2 

CLUSTER MJK.CLUSTERl 

HISTORY 

OWNER-IDENT OWNCLUST 

RELEASE 2 

DATA MJK. CLUSTER. DATA 

HISTORY 

OWNER-IDENT ( NULL) 

RELEASE 2 

VOLUMES 

VOLSER 33300 1 

INDEX MJK. CLUSTER I. INDEX 

HISTORY 

OWNER-IDENT ( NULL ) 

RELEASE 2 

VOLUMES 

VOLSER --333001 

GOG BASE MJK.GDG1 

HISTORY 

OWNER-IDENT — OWNGDG 

RELEASE > 2 

NONVSAM MJK.GDG1.G0001V00 

HISTORY 

OWNER-IDENT ( NULL ) 

RELEASE 2 

VOLUMES 

VOLSER 333001 

VOLSER 333002 



CREATION 77.040 

EXPIRATION 00 . 000 

CREATION- 77.040 

EXPIRATION 00 . 000 

DEVTYPE X ' 30502009 » 

CREATION 77 . 040 

EXPIRATION 00 . 000 

DEVTYPE X' 30502009' 

CREATION 77.040 

EXPIRATION 00 .000 

CREATION 77.040 

EXPIRATION 77. 140 

CREATION 77.040 

EXPIRATION 00 . 000 

DEVTYPE X' 30502009' 

CREATION 77 . 040 

EXPIRATION 00 . 000 

DEVTYPE X' 30502009' 

CREATION 77.040 

EXPIRATION 99.365 

CREATION 77.040 

EXPIRATION—' 00.000 

DEVTYPE X ' 30502009 ' 

DEVTYPE X ' 30502009 ' 



RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 • 

RCVY-VOL 33300 1 RCVY-CI- 

RCVY-DEVT X ' 30502009 ' 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 ' 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 * 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 ' 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X' 30502009' 

RCVY-VOL 33300 1 RCVY-CI- 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X' 30502009' 



-X'000010' 



-X'000011' 



-X'000012' 



-X'000014' 



-X'OOOOOE' 



-X'OOOOOD' 



-X'OOOOOF' 



-X'000015' 



-X'000016' 



Figure 18 (Part 1 of 2). An Example of LISTCAT VOLUME Output 
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NONVSAM MJK.NONVSAM1 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

VOLUMES 

VOLSER— — 333001 

CLUSTER HJKCAT 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 



CREATION 

EXPIRATION- 



-77.040 
-00.000 



DEVTYPE- 



CREATION — 
EXPIRATION- 



DATA 

HISTORY 

OWNER-IDENT 
RELEASE 

VOLUMES 

VOLSER 



VSAM . CATALOG . BASE . DATA. RECORD 



-(NULL) 
2 



CREATION 

EXPIRATION- 



INDEX — 

HISTORY 

OWNER-IDENT 
RELEASE 

VOLUMES 

VOLSER 



333001 DEVTYPE 

VSAM.CATALOG.BASE . INDEX. RECORD 



-(NULL) 



CREATION 

EXPIRATION- 



-333001 



DEVTYPE- 



VOLUME 

HISTORY 

RELEASE- 
VOLUMES 

VOLSER— 



333001 



2 

-333001 



RCVY-VOL- 
DEVTYPE— 



-X" 30502009" 



-77.040 
-99.999 



-00.000 
-00.000 



-X" 30502009' 



-00.000 
-00.000 



-X' 30502009' 



333001 

--X'30502009' 



RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 



RCVY-CI- 



-X'OOOOIS' 



RCVY-DEVT- 



-X '30502009 ' 



RCVY-CI- 



-X' 000009' 



LISTING FROM CATALOG 



MJKCAT 



THE NUMBER OF ENTRIES PROCESSED WAS: 

1 

>_0 

2 

3 

1 

3 

2 



1 

1 

o 

14 



AIX 

ALIAS ■■- 

CLUSTER 

DATA 

GDG 

INDEX 

NONVSAM 

PAGESPACE — 

PATH 

SPACE 

USERCATALOG 
TOTAL 



THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 
IDC0001I FUNCTION COMPLETED, HIGHEST CONOITION CODE WAS 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 18 (Part 2 of 2). An Example of LISTCAT VOLUME Output 
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LISTCAT SPACE ALL OUTPUT LISTING 



When the LISTCAT command is specified with the SPACE and ALL 
parameters, all the information for each volume entry in the 
catalog is listed (see Figure 19). You can use this type of 
listing to determine how space on each cataloged volume is 
allocated to VSAM data spaces. You may have to list the volume's 
table of contents (VTOC) to determine how all of the volume's 
space is allocated. 



/* LIST VOLUME INFORMATION FOR THE VOLUMES 
CONTROLLED BY THE CATALOG */ 
LISTCAT - 
SPACE - 
ALL - 
CATALOG( MJKCAT) 



LISTING FROM CATALOG « MJKCAT 



VOLUME 333001 

HISTORY 

RELEASE 2 

CHARACTERISTICS 

BYTES/TRK 13165 

TRKS/CYL 19 

CYLS/VOL 411 

DATASPACE 

DATASETS 5 

EXTENTS • 1 

SEC-ALLOC 40 

TYPE TRACK 

EXTENT-DESCRIPTOR: 

TRACKS-TOTAL 160 

TRACKS-USED 89 

DATASET-DIRECTORY: 

DSN MJKCAT 

DSN MJK. CLUSTER. DATA 

DSN MJK. CLUSTER1. INDEX 

DSN MJK . ALT . INDEX1 . DATA 

DSN :-MJK . ALT . INDEX1 . INDEX 



RCVY-VOL 333001 

DEVTYPE X ' 30502009 ' 

VOLUME-TIMESTAMP: 

X'8A51B6A76850E000' 


RCVY-DEVT X' 

MAX-PHYREC-SZ-- 


30502009' 
13030 


DATASETS-ON-VOL ■ ! 

DATASPCS-ON-VOL : 






FORMAT- 1-DSCB: 

CCHHR X ' 0000000 103 ' 

TIMESTAMP 

X'8A51B61D97B04000' 

BEG-CCHH X' 00000002' 


ATTRIBUTES: 
SUBALLOC 
EXPLICIT 
USERCAT 

SPACE-MAP 


5947 





ATTRIBUTES—- (NULL) 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 

ATTRIBUTES ( NULL ) 



EXTENTS 3 

EXTENTS ■ 1 

EXTENTS 1 

EXTENTS 1 

EXTENTS 1 



LISTING FROM CATALOG 



MJKCAT 



THE NUMBER OF ENTRIES PROCESSED MAS: 

AIX 

ALIAS 

CLUSTER 

DATA 

GDG —0 

INDEX 

NONVSAM 

PAGESPACE 

PATH 

SPACE 1 

USERCATALOG 

TOTAL r 1 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 



Figure 19. An Example of LISTCAT SPACE ALL Output 
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LISTCAT ALL OUTPUT LISTING 



When you specify the LISTCAT command and include the ALL 
parameter, all the information for each catalog entry is listed 
(see Figure 20). This example illustrates the LISTCAT output for 
each type of catalog Qntry. You can use this type of listing to 
obtain all cataloged information (except password and security 
information) about each entry that is listed. When you want to 
list an entry's passwords, you must provide the catalog's master 
password (which results in listing the passwords of each 
password-protected entry) or each entry's master password. 

Not© : When ENTRIES is specified, you specify only those 
entrynames that identify catalog entries which are not volume 
entries. If a volume serial number is specified with the ENTRIES 
parameter, entrynames of other entry types cannot also be 
specified. However, if the ENTRIES parameter is not specified 
and if entry types are not specified (that is, CLUSTER, SPACE, 
DATA, etc.), all entries in the catalog, including volume 
entries, are listed. 



/* LIST ALL CATALOGED INFORMATION FOR EACH ENTRY 
LISTCAT - 
ALL - 
CATALOG (MJKCAT) 



*/ 



LISTING FROM CATALOG — MJKCAT 



AIX MJK.ALT.INDEXI 

HISTORY 

OWNER-IDENT (NULL ) 

RELEASE 2 

PROTECTION-PSWD (NULL ) 

ASSOCIATIONS 

DATA MJK.ALT.INDEXI. DATA 

INDEX MJK.ALT.INDEXI. INDEX 

C LUSTER— M JK .CLUSTER 1 
PATH MJK.AIX1 .PATH 

ATTRIBUTES 
UPGRADE 

DATA MJK.ALT.INDEXI. DATA 

HISTORY 

OWNER-IDENT ( NULL ) 

RELEASE 2 

PROTECTION-PSWD ( NULL ) 

ASSOCIATIONS 

AIX MJK.ALT.INDEXI 

ATTRIBUTES 

KEYLEN 5 

RKP 5 

AXRKP— —————— ———————45 

SHROPTNS( 1,3) RECOVERY 
UNORDERED NOREUSE 

STATISTICS 

REC-TOTAL 4 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 6 

SPACE-SEC 6 

VOLUME 

VOLSER 333001 

DEVTYPE X ' 30502009 ■ 

VOLFLAG PRIME 

EXTENTS: 

LOW-CCHH X ' 00040008 ' 

HIGH-CCHH X ' 0004000D ' 



CREATION 77 . 040 

EXPIRATION 00 . 000 

RACF (NO ) 



CREATION 77.040 

EXPIRATION 00.000 

RACF (NO ) 

AVGLRECL 4086 

MAXLRECL 32600 

SUBALLOC NOERASE 
SPANNED NONUNIQKEY 

SPLITS-CI— 

SPLITS-CA 

FREESPACE-ZCI 

FREESPACE-tfCA 

FREESPC-BYTES 69632 

HI-ALLOC-RBA 73728 

HI-USED-RBA 73728 

PHYREC-SIZE 4096 

PHYRECS/TRK -3 

TRACKS/CA 6 

LOW-RBA 

HIGH-RBA 73727 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 • 



RCVY-CI- 



-X'000010' 



RCVY-VOL— 
RCVY-DEVT- 



333001 

-X' 30502009' 



RCVY-CI- 



-X'OOOOH 1 



BUFSPACE 8704 

EXCPEXIT ( NULL ) 

INDEXED NOWRITECHK 

EXCPS 7 

EXTENTS 1 

SYSTEM-TIMESTAMP: 

X'8A51B6C0C87CF000' 



HI-ALLOC-RBA 73728 

HI-USED-RBA 73728 

TRACKS 6 



CISIZE- 
CI/CA— 



-4096 
18 



NOIMBED 



NOREPLICAT 



EXTENT-NUMBER- 
EXTENT-TYPE — 



-X'00* 



Figure 20 (Part 1 of 7). An Example of LISTCAT ALL Output 
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INDEX MJK. ALT. INDEX1. INDEX 

HISTORY 

OMNER-IDENT ( NULL ) 

RELEASE-- 2 

PROTECTION-PSWD ( NULL ) 

ASSOCIATIONS 

AIX MJK.ALT.INDEX1 

ATTRIBUTES 

KEYLEN 5 

RKP 5 

SHROPTNS( 1,3) RECOVERY 
NOREUSE 

STATISTICS 

REC-TOTAb- 1 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 1 

SPACE-SEC \ 

VOLUME 

VOLSER 333001 

DEVTYPE X' 30502009' 

VOLFLAG PRIME 

EXTENTS: 

LOW-CCHH X ' 0004000E ' 

HIGH-CCHH X ' 0004000E ' 

PATH MJK. AIX1. PATH 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

PROTECTION-PSWD (NULL) 

ASSOCIATIONS 

AIX MJK . ALT . INDEX1 

DATA MJK.ALT.INDEX1 .DATA 

INDEX MJK. ALT. INDEX1. INDEX 

DATA MJK. CLUSTER. DATA 

INDEX MJK. CLUSTER1. INDEX 

ATTRIBUTES 
UPDATE 



CREATION 77 . 040 

EXPIRATION 00 . 000 

RACF (NO) 

AVGLRECL 

MAXLRECL 505 

SUBALLOC NOERASE 

SPLITS-CI 

SPLITS-CA 

FREESPACE-XCI 

FREESPACE-/XA 

FREESPC-BYTES 9728 

HI-ALLOC-RBA 10240 

HI-USED-RBA 512 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 1 

LOM-RBA 

HIGH-RBA 10239 

CREATION 77.040 

EXPIRATION 00 . 000 

RACF (NO) 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 • 



BUFSPACE 

EXCPEXIT (NULL ) 

NOWRITECHK NOIMBED 

EXCPS 3 

EXTENTS 1 

SYSTEM-TIMESTAMP: 

X'8A51B6C0C87CFOOO' 



HI-ALLOC-RBA 10240 

HI-USED-RBA 512 

TRACKS 1 



RCVY-VOL 333001 

RCVY-DEVT -X' 30502009' 



RCVY-CI- 



-X' 000012' 



CISIZE 

CI/CA 

NOREPLICAT 



512 

20 

UNORDERED 



INDEX: 

LEVELS 1 

ENTRIES/SECT 4 

SEQ-SET-RBA 

HI-LEVEL-RBA 



EXTENT-NUMBER- 
EXTENT-TYPE — 



-X'OO' 



RCVY-CI- 



-X'000014' 



CLUSTER MJK.CLUSTER1 

HISTORY 

OWNER-IDENT OWNCLUST 

RELEASE 2 

PROTECTION 

MASTERPW MASTCL 

CONTROLPW CNTLCJ. 

USAR (NONE ) 

ASSOCIATIONS 

DATA MJK.CLUSTER1 .DATA 

INDEX MJK. CLUSTER1 .INDEX 

AIX MJK . ALT . INDEX1 



CREATION 77.040 

EXPIRATION 77.140 

UPDATEPW UPDCL 

READPW READCL 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 

CODE CODECL 

ATTEMPTS—- 3 



RCVY-CI X ' 00000E ' 

RACF (NO) 

USVR (NULL) 



Figure 20 (Part 2 of 7). An Example of LISTCAT ALL Output 
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DATA MJK.CLUSTER.DATA 

HISTORY 

OWNER-IDENT ( NULL ) 

RELEASE 2 

PROTECTION-PSWO ( NULL ) 

ASSOCIATIONS 

CLUSTER--MJK . CLUSTER 1 

ATTRIBUTES 

KEYLEN 5 

RKP 5 

SHROPTNS( 1,3) RECOVERY 
UNORDERED NOREUSE 

STATISTICS 

REC-TOTAL 20 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 20 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 2 

SPACE-SEC 2 

VOLUME 

VOLSER 333001 

DEVTYPE X ' 30502009 ' 

VOLFLAG PRIME 

EXTENTS: 

LOM-CCHH X ' 00040005 • 

HIGH-CCHH X ' 00040006 ' 

INDEX MJK. CLUSTER 1. INDEX 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

PROTECTION-PSND (NULL) 

ASSOCIATIONS 

CLUSTER--MJK.CLUSTER1 

ATTRIBUTES 

KEYLEN 5 

RKP— 5 

SHROPTNS( 1,3) RECOVERY 
NOREUSE 

STATISTICS 

REC-TOTAL 1 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 1 

SPACE-SEC 1 

VOLUME 

VOLSER 333001 

DEVTYPE X ' 30502009 • 

VOLFLAG PRIME 

EXTENTS: 

LOM-CCHH X • 00040007 • 

HIGH-CCHH X" 00040007' 

GDG BASE MJK.GDG1 

HISTORY 

OWNER-IDENT OWNGDG 

RELEASE 2 

ATTRIBUTES 

LIMIT 250 

ASSOCIATIONS 

NONVSAM-- MJK.GDG1 .G0001V00 



CREATION 77.040 

EXPIRATION 00 . 000 

RACF ( NO ) 

AVGLRECL 80 

MAXLRECL 100 

SUBALLOC NOERASE 
NONSPANNED 

SPLITS-CI 

SPLITS-CA 

FREESPACE-ZCI 15 

FREESPACE-ZCA 20 

FREESPC-BYTES 12288 

HI-ALLOC-RBA 24576 

HI-USED-RBA 24576 

PHYREC-SI2E 4096 

PHYRECS/TRK 3 

TRACKS/CA 2 

LOW-RBA 

HIGH-RBA 24575 

CREATION 77. 040 

EXPIRATION 00 . 000 

RACF ( NO ) 

AVGLRECL 

MAXLRECL 505 

SUBALLOC NOERASE 

SPLITS-CI 

SPLITS-CA — 

FREESPACE-ZCI 

FREESPACE-XCA 

FREESPC-BYTES 9728 

HI-ALLOC-RBA 10240 

HI-USED-RBA 512 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 1 

LOW-RBA 

HIGH-RBA 10239 

CREATION 77.040 

EXPIRATION 99. 365 



RCVY-VOL— 
RCVY-DEVT- 



333001 

-X* 30502009' 



RCVY-CI- 



-X'OOOOOD' 



BUFSPACE 25088 

EXCPEXIT EXITCLUS 

INDEXED NOWRITECHK 

EXCPS 4 

EXTENTS- 1 

SYSTEM-TIMESTAMP: 

X'8A51B6ACD5B92000' 



HI-ALLOC-RBA 24576 

HI-USED-RBA 24576 

TRACKS 2 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 



BUFSPACE 

EXCPEXIT EXITCLUS 

NOWRITECHK NOIMBED 

EXCPS 4 

EXTENTS 1 

SYSTEM-TIMESTAMP: 

X'8A51B6ACD5B92000' 



HI-ALLOC-RBA 10240 

HI-USED-RBA 512 

TRACKS 1 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 



CISIZE— 

CI/CA 

NOIMBED 



12288 

2 

NOREPLICAT 



EXTENT-NUMBER- 
EXTENT-TYPE — 



-X'OO' 



RCVY-CI- 



-X'OOOOOF' 



CISIZE 

CI/CA 

NOREPLICAT 



512 

20 

UNORDERED 



INDEX: 

LEVELS 1 

ENTRIES/SECT 1 

SEQ-SET-RBA 

HI-LEVEL-RBA 



EXTENT-NUMBER- 
EXTENT-TYPE— 



-X'OO' 



RCVY-CI- 



-X'000015' 



SCRATCH 



EMPTY 



Figure 20 (Part 3 of 7). An Example of LISTCAT ALL Output 
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— MJK.GOG1.G0001V00 



NONVSAM - 
HISTORY 

OHNER-IDENT 

RELEASE 

VOLUMES 

VOLSER—— 

VOLSER 

ASSOCIATIONS 

606 MJK.G0G1 

ALIAS MJK.GDG1 .ALIAS 



(NULL) 
2 



333001 
333002 



CREATION 

EXPIRATION- 



DEVTYPE- 
DEVTYPE- 



-77.040 
-00.000 



-X' 30502009' 
-X'30502009'- 



RCVY-VOL * 333001 

RCVY-DEVT X ' 30502009 • 



FSEQN- 
FSEQN- 



RCVY-CI- 



-X" 000016' 



ALIAS NJK.GDG1. ALIAS 

HISTORY 

RELEASE —2 

ASSOCIATIONS 

NONVSAH— HJK. GDG1 . G0001V00 



RCVY-VOL- 



-333001 



RCVY-DEVT X' 30502009* 



RCVY-CI- 



-X'000017' 



NONVSAH MJK.NONVSAM1 

HISTORY 

OHNER-IDENT (NULL ) 

RELEASE 2 

VOLUMES 

VOLSER 333001 DEVTYPE- 

ASSOCIATIONS (NULL) 



CREATION 77. 040 

EXPIRATION 01 . 000 



-X* 30502009' 



RCVY-VOL— 
RCVY-DEVT- 



—333001 

-X' 30502009' 



RCVY-CI- 



-X' 000018' 



FSEQN- 



CLUSTER HJKCAT 

HISTORY 

OHNER-IDENT 1 NULL ) 

RELEASE ; 2 

PROTECTION-PSHD— ( NULL ) 

ASSOCIATIONS 

DATA VSAH. CATALOG . BASE . DATA .RECORD 

INDEX VSAM . CATALOG . BASE . INDEX .RECORD 



CREATION 

EXPIRATION- 
RACF 



-77.040 
-99.999 
—(NO) 



Figure* 20 (Part 4 of 7). An Example of LISTCAT ALL Output 
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DATA VSAM. CATALOG. BASE 

HISTORY 

OHNER-IDENT ( NULL ) 

RELEASE t -2 

PROTECTXON-PSMO ( NULL ) 

ASSOCIATIONS 
CLUSTER— MJKCAT 

ATTRIBUTES 

KEYLEN 44 

RKP 

SHR0PTNSC3.3) RECOVERY 
UNORDERED NOREUSE 

STATISTICS 

REC-TOTAL 15 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 57 

SPACE-SEC 18 

VOLUME 

VOLSER 33300 1 

DEVTYPE X' 30502009' 

V0LFLA6 PRIME 

LOW-KEY 00 

HIGH-KEY- 3F 

HI-KEY-RBA — •* 144 

EXTENTS: 

LOH-CCHH X • 00000002 ■ 

HIGH-CCHH X' 00020011 ' 

VOLUME 

VOLSER 333001 

DEVTYPE X • 30502009 • 

V0LFLA6 -PRIME 

LOM-KEY 40 

HIGH-KEY FF 

HI-KEY-RBA 368640 

EXTENTS • 

LOH-CCHH X' 00030002' 

HIGH-CCHH X ' 00030004 ' 



DATA.RECORO 

CREATION 00 . 000 

EXPIRATION 00 . 000 

RACF ( NO ) 

AVGLRECL 505 

MAXLRECL 505 

SUBALLOC NOERASE 
NONSPANNED BIND 

SPLITS-CI 

SPLITS-CA 

FREESPACE-XCI 

FREESPACE-XCA 

FREESPC-BYTES 381952 

HI-ALLOC-RBA 3891 20 

HI-USED-RBA 389120 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 



LOH-RBA 

HIGH-RBA 368639 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 



BUFSPACE 3072 

EXCPEXIT ( NULL > 

INDEXED NOWRITECHK 
RECVABLE 

EXCPS 24 

EXTENTS 2 

SYSTEM-TIMESTAMP: 

X'8A51B6244C1B1000' 



CISIZE- 
CI/CA— 
IMBED 



512 

40 

NOREPLICAT 



HI-ALLOC-RBA- 
HI-USED-RBA— 



-368640 
—20480 



EXTENT-NUMBER-* 1 

EXTENT-TYPE X ' 00 ' 



TRACKS 54 

HI-ALLOC-RBA 389120 

HI-USED-RBA 389120 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'OO' 



LOH-RBA— 
HIGH-RBA- 



-368640 
-389119 



TRACKS- 



Figure 20 (Part 5 of 7). An Example of LISTCAT ALL Output 
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INDEX VSAM.CATALOG.BASE. 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

PROTECTION-PSWD (NULL) 

ASSOCIATIONS 
CLUSTER— HJKCAT 

ATTRIBUTES 

KEYLEN 44 

RKP 

SHROPTNS( 3,3) RECOVERY 
NOREUSE BIND 

STATISTICS 

REC-TOTAL 3 

REC-OELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 3 

SPACE-SEC 3 

VOLUME 

VOLSER 333001 

DEVTYPE X • 30502009 ' 

V0LFLA6 PRIME 

EXTENTS: 

LOW-CCHH X' 00020012' 

HIGH-CCHH X' 00030001 ' 

VOLUME 

VOLSER 333001 

DEVTYPE X ' 30502009 ' 

VOLFLAG PRIME 

LOW-KEY 00 

HIGH-KEY 3F 

EXTENTS: 

LOW-CCHH X' 00000002 • 

HIGH-CCHH X •00020011' 

VOLUME 

VOLSER 333001 

DEVTYPE X' 30502009* 

VOLFLAG PRIME 

LOW-KEY -40 

HIGH-KEY FF 

EXTENTS: 

LOW-CCHH X ' 00030002 ' 

HIGH-CCHH X ' 00030004 • 



INDEX. RECORD 

CREATION 00 . 000 

EXPIRATION 00 . 000 

RACF ( NO ) 

AVGLRECL 

MAXLRECL 505 

SUBALLOC NOERASE 

SPLITS-CI 

SPLITS-CA 

FREESPACE-XCI 

FREESPACE-/XA 

FREESPC-BYTES 38912 

HI-ALLOC-RBA 40448 

HI-USED-RBA 40448 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 1 

LOW-RBA <— 

HIGH-RBA- 30719 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 

LOW-RBA 30720 

HIGH-RBA 39935 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 

LOW-RBA 39936 

HIGH-RBA W447 



BUFSPACE 

EXCPEXIT (NULL) 

NOWRITECHK IMBED 

EXCPS 13 

EXTENTS 3 

SYSTEM-TIMESTAMP: 

X'8A51B6244C1B1000' 



HI-ALLOC-RBA- 30720 

HI-USED-RBA 512 

TRACKS 3 

HI-ALLOC-RBA 39936 

HI-USED-RBA 31232 



TRACKS-— -54 

HI-ALLOC-RBA— - 40448 

HI-USED-RBA— r-- 40448 



CISIZE 

CI/CA 

NOREPLICAT 



512 

20 

UNORDERED 



INDEX: 

LEVE LS 2 

ENTRIES/SECT 7 

SEQ-SET-RBA 30720 

HI-LEVEL-RBA 



EXTENT-NUMBER- 
EXTENT-TYPE 



1 

-X'OO' 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'80' 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'80" 



TRACKS- 
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VOLUME 333001 

HISTORY 

RELEASE 2 RCVY-VOL- 

CHARACTERISTICS 

BYTES/TRK 13165 

TRKS/CYL 19 

CYLS/VOL 411 

DATASPACE 

DATASETS 5 

EXTENTS 1 

SEC-ALLOC 40 

TYPE TRACK 

EXTENT-DESCRIPTOR : 

TRACKS-TOTAL 160 BEG-CCHH- 

TRACKS-USED 89 

OATASET-DIRECTORY: 

DSN MJKCAT 

DSN MJK. CLUSTER. DATA 

DSN NJK .CLUSTER 1 . INDEX 

DSN MJK.ALT.INDEXl'.DATA 

DSN MJK. ALT. INDEX1. INDEX 



-333001 



DEVTYPE X ' 30502009 ' 

VOLUME-TIMESTAHP: 

X'8A51B6A76850E000' 

FORMAT- 1-DSCB: 

CCHHR X' 0000000103' 

TIMESTAMP 

X'8A51B61D97B04000' 



-X'00000002' 



RCVY-DEVT X ' 30502009 ' 



RCVY-CI- 



-X' 000009' 



MAX-PHYREC-SZ- 
MAX-EXT/ALLOC- 



-13030 
5 



DATASETS-ON-VOL 5 

DATASPCS-ON-VOL 1 



ATTRIBUTES: 
SUBALLOC 
EXPLICIT 
USERCAT 

SPACE-MAP 5947 

ATTRIBUTES (NULL ) 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL ) 

ATTRIBUTES ( NULL ) 



EXTENTS 3 

EXTENTS 1 

EXTENTS 1 

EXTENTS 1 

EXTENTS 1 



LISTING FROM CATALOG 



MJKCAT 



THE NUMBER OF ENTRIES PROCESSEO WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GOG 1 

INDEX 3 

NONVSAM 2 

PAGESPACE 

PATH 1 

SPACE 1 

USERCATALOG 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED NAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE MAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE NAS 



Figure 20 (Part 7 of 7). An Example of LISTCAT ALL Output 
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LISTCAT ALLOCATION OUTPUT LISTING 



When you specify the LISTCAT command and include the ALLOCATION 
parameter, each cataloged object with space allocated to it from 
a VSAM data space is listed (see Figure 21). All information 
about the object's space is listed, but none of the object's 
other cataloged information is listed. The entry types that can 
be specified when the ALLOCATION parameter is specified are 
limited to DATA and INDEX. 



/» 



LIST SPACE ALLOCATION INFORMATION «/ 



LISTCAT - 

ALLOCATION - 
CATALOG(HJKCAT) 



AIX MJK.ALT.INDEX1 

HISTORY 

OHNER-IDENT ( NULL ) 

RELEASE 2 

DATA MJK. ALT. INOEX1. DATA 

HISTORY 

OWNER-IDENT- ( NULL ) 

RELEASE 2 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI— 6 

SPACE-SEC 6 

VOLUME 

VOLSER 33300 1 

DEVTYPE— X ' 30502009 • 

VOLFLAG PRIME 

EXTENTS: 

LOH-CCHH X ' 00040008 ' 

HIGH-CCHH X' 0004000D ' 

INDEX MJK.ALT.INDEX1. INDEX 

HISTORY 

OWNER-IDENT (NULL ) 

RELEASE 2 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 1 

SPACE-SEC 1 

VOLUME 

VOLSER— 333001 

DEVTYPE X' 30502009' 

VOLFLAG PRIME 

EXTENTS: 

LOH-CCHH X ' 0004000E • 

HIGH-CCHH X'0004000E' 

PATH MJK. AIX1. PATH 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

CLUSTER MJK. CLUSTER 1 

HISTORY 

OWNER-IDENT OWNCLUST 

RELEASE 2 



CREATION 77. 040 

EXPIRATION 00 . 000 

CREATION 77 . 040 

EXPIRATION 00 . 000 

HI-ALLOC-RBA 73728 

HI-USED-RBA —73728 

PHYREC-SIZE 4096 

PHYRECS/TRK 3 

TRACKS/CA 6 

LOW-RBA 

HIGH-RBA 73727 

CREATION 77 . 040 

EXPIRATION 00 . 000 

HI-ALLOC-RBA 1 0240 

HI-USED-RBA ■» — 51 2 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 1 

LOW-RBA 

HIGH-RBA 10239 

CREATION 77 . 040 

EXPIRATION 00 .000 

CREATION 77.040 

EXPIRATION 77. 040 



RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 • 



-X'000010' 



RCVY-VOL 333001 RCVY-CI- 

RCVY-DEVT X ' 30502009 • 



-X' 000011* 



HI-ALLOC-RBA 73728 EXTENT-NUMBER- 

HI-USED-RBA 73728 EXTENTS-TYPE 

TRACKS —6 

RCVY-VOL 33300 1 RCVY-CI 

RCVY-DEVT- X ' 30502009 ' 



-X'OO' 



-X' 000012' 



HI-ALLOC-RBA 10240 EXTENT-NUMBER- 

HI-USED-RBA 512 EXTENT-TYPE — 

TRACKS 1 

RCVY-VOL 33300 1 RCVY-CI 

RCVY-DEVT X' 30502009' 

RCVY-VOL 33300 1 RCVY-CI 

RCVY-DEVT X' 30502009' 



-X'40' 



-X'000014' 



-X'OOOOOE' 



Figure 21 (Part 1 of 3). An Example of LISTCAT ALLOCATION Output 
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DATA 



MJK. CLUSTER. DATA 



HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 2 

SPACE-SEC 2 

VOLUME 

VOLSER 333001 

DEVTYPE X ' 30502009 • 

VOLFLAG PRIME 

EXTENTS: 

LOM-CCHH X ' 00040005 ' 

HIGH-CCHH X' 000*0006" 



CREATION 

EXPIRATION- 



HI-ALLOC-RBA- 
HI-USED-RBA— 



PHYREC-SIZE- 
PHYRECS/TRK- 
TRACKS/CA 



LOH-RBA-- 
HIGH-RBA- 



-77.0*0 
-00.000 



-24576 
-24576 



-6144 

2 

2 





-24575 



RCVY-VOL 333001 

RCVY-DEVT X* 30502009' 



HI-ALLOC-RBA -24576 

HI-USED-RBA 24576 

TRACKS 2 



RCVY-CI- 



-X'OOOOOD' 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'OO' 



MJK. CLUSTER1. INDEX 



INDEX — 
HISTORY 

OWNER-IDENT 

RELEASE 

ALLOCATION 

SPACE-TYPE- 

SPACE-PRI— 

SPACE-SEC— 
VOLUME 

VOLSER 33300 1 

DEVTYPE X ' 30502009 • 

VOLFLAG PRIME 

EXTENTS: 

LOM-CCHH X ' 00040007 • 

HIGH-CCHH X ' 00040007 ' 



(NULL) 
2 



TRACK 

1 

1 



CREATION 

EXPIRATION- 



HI-ALLOC-RBA- 
HI-USED-RBA— 



PHYREC-SIZE- 
PHYRECS/TRK- 
TRACKS/CA 



LOM-RBA— 
HIGH-RBA- 



-77.040 
-00.000 



-10240 
— 512 



-512 
—20 
1 





-10239 



RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 



HI-ALLOC-RBA 10240 

HI-USED-RBA 512 

TRACKS 1 



RCVY-CI- 



-X'OOOOOF' 



EXTENT-NUMBER- 
EXTENT-TYPE— 



-X'OO' 



CLUSTER MJKCAT 

HISTORY 

OMNER-IDENT ( NULL ) 

RELEASE 2 



CREATION 

EXPIRATION- 



-77.040 
-99.999 



-512 
—.20 
— 3 



DATA VSAM.CATALOG.BASE.DATA. RECORD 

HISTORY 

OMNER-IDENT (NULL) CREATION 00.000 

RELEASE 2 EXPIRATION 00 . 000 

ALLOCATION 

SPACE-TYPE— TRACK 

SPACE-PRI 57 HI-ALLOC-RBA 389120 

SPACE-SEC 18 HI-USED-RBA 389120 

VOLUME 

VOLSER- 333001 PHYREC-SIZE 

DEVTYPE— X ' 30502009 ' PHYRECS/TRK 

VOLFLAG PRIME TRACKS/CA 

LOH-KEY 00 

HIGH-KEY > 3F 

HI-KEY-RBA 6144 

EXTENTS: 

LOM-CCHH X ' 00000002 ' LOM-RBA 

HIGH-CCHH X ' 000200 1 1 ' HI6H-RBA 368639 

VOLUME 

VOLSER 333001 PHYREC-SIZE 

DEVTYPE— X' 30502009' PHYRECS/TRK 

VOLFLAG PRIME TRACKS/CA 

LOH-KEY 40 

HIGH-KEY FF 

HI-KEY-RBA -. 368640 

EXTENTS: 

LOM-CCHH X ' 00030002 • LOM-RBA 368640 

HIGH-CCHH X ' 00030004 • HIGH-RBA 3891 19 



-512 
--20 
— 3 



HI-ALLOC-RBA- 
HI-USED-RBA— 



-368640 
—20480 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'OO' 



TRACKS 54 

HI-ALLOC-RBA 389120 

HI-USED-RBA 389120 



EXTENT-NUMBER- 
EXTENT-TYPE 



-X'OO' 



TRACKS- 



Figure 21 (Part 2 of 3). An Example of LISTCAT ALLOCATION Output 
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INDEX VSAM. CATALOG. BASE 

HISTORY 

OWNER-IDENT < NULL ) 

RELEASE 2 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 3 

SPACE-SEC 3 

VOLUME 

VOLSER 333001 

DEVTYPE X' 30502009' 

VOLFLAG PRIME 

EXTENTS: 

LOM-CCHH X' 00020012 ' 

HIGH-CCHH- X 1 00030001 * 

VOLUME 

VOLSER 333001 

DEVTYPE X' 30502009* 

VOLFLAG PRIME 

LOW-KEY 00 

HIGH-KEY 3F 

EXTENTS: 

LOH-CCHH X ' 00000002 ' 

HIGH-CCHH X* 00020011' 

VOLUME 

VOLSER 33300 1 

DEVTYPE X ' 30502009 ' 

VOLFLAG PRIME 

LOW-KEY 40 

HIGH-KEY FF 

EXTENTS: 

LOM-CCHH X' 00030002' 

HIGH-CCHH X ' 00030004 ' 



INDEX. RECORD 

CREATION— 00 .000 

EXPIRATION t— 00 . 000 

HI-ALLOC-RBA -40448 

HI-USED-RBA 40448 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 1 

LOM-RBA 

HIGH-RBA 30719 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 

LOH-RBA 30720 

HIGH-RBA 39935 

PHYREC-SIZE 512 

PHYRECS/TRK 20 

TRACKS/CA 3 

LOM-RBA 39936 

HIGH-RBA 40447 



HI-ALLOC-RBA 30720 

HI-USED-RBA 512 

TRACKS 3 

HI-ALLOC-RBA 39936 

HI-USED-RBA 31232 



TRACKS 54 

HI-ALLOC-RBA 40448 

HI-USED-RBA 40448 



EXTENT-NUMBER- 
EXTENT-TYPE — 



1 

-X'OO' 



EXTENT-NUMBER- 
EXTENT-TYPE — 



-X*80' 



EXTENT-NUMBER- 
EXTENT-TYPE — 



-X'80' 



TRACKS- 



LISTING FROM CATALOG — MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 

CLUSTER 2 

DATA 3 

GOG 

INDEX 3 

NONVSAM 

PAGESPACE 

PATH 1 

SPACE 

USERCATALOG 

TOTAL 10 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED HAS 

XDC0001X FUNCTION COMPLETED, HIGHEST CONDITION CODE HAS 

IOC0002X IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE HAS 

Figure 21 (Part 3 of 3). An Example of LISTCAT ALLOCATION Output 



432 0S/VS2 Access Method Services 



LISTCAT HISTORY OUTPUT LISTING 



When you specify the LISTCAT command end include the HISTORY 
parameter, only the name, ownerid, creation date, and expiration 
date are listed for each entry that is selected (see Figure 22). 
Only these types of entries have HISTORY information 1 
ALTERNATEINDEX, CLUSTER, DATA, INDEX, NONVSAM, and PATH. 



/» LIST HISTORY INFORMATION FOR EACH ENTRY «/ 

LISTCAT - 
HISTORY - 
CATALOG(HJKCAT) 



LISTING FROM CATALOG — MJKCAT 



AIX MJK.ALT.INDEX1 

HISTORY 

OWNER-IDENT -( NULL ) 

RELEASE 2 

-— MJK. ALT. INDEX1. DATA 



CREATION 

EXPIRATION- 



DATA 

HISTORY 

OWNER-IDENT (NULL) CREATION 

RELEASE 2 EXPIRATION- 



INDEX — 
HISTORY 

OWNER-IDENT 
RELEASE 



MJK . ALT . INDEX1 . INDEX 



-(NULL) 
2 



PATH 

HISTORY 

OWNER-IDENT 
RELEASE 



MJK. AIX1. PATH 



-(NULL) 
2 



CLUSTER MJK.CLUSTER1 

HISTORY 

OWNER-IDENT OWNCLUST 

RELEASE 2 



DATA 

HISTORY 

OWNER-IDENT 
RELEASE 



MJK. CLUSTER. DATA 



-(NULL) 
2 



INDEX — 
HISTORY 

OWNER-IDENT 
RELEASE 



MJK. CLUSTER 1. INDEX 



-(NULL) 
2 



GDG BASE MJK.GDGX 

HISTORY 

OWNER-IDENT-- 
RELEASE 



-OWNGDG 
2 



NONVSAM MJK.GDG1.G0001V00 

HISTORY 

OWNER-IDENT (NULL ) 

RELEASE 2 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



CREATION 

EXPIRATION- 



-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X' 30502009" 

-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X' 30502009' 

-77.040 RCVY-VOL >=• 333001 

-00.000 RCVY-DEVT X' 30502009' 

-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X' 30502009' 

-77.040 RCVY-VOL 333001 

-77.140 RCVY-DEVT X' 30502009' 

-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X' 30502009' 

-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X' 30502009' 

-75.223 RCVY-VOL 333001 

-99.365 RCVY-DEVT X' 30502009* 

-77.040 RCVY-VOL 333001 

-00.000 RCVY-DEVT X* 30502009' 



RCVY-CI X' 000010 ' 



RCVY-CI X' 000011' 



RCVY-CI tX* 000012 ' 



RCVY-CI X' 000014' 



RCVY-CI X ' 00000E ' 



RCVY-CI X' 00000D ' 



RCVY-CI X' 00000F ' 



RCVY-CI X ' 000015 ' 



RCVY-CI X' 000016 ' 



ALIAS 



MJK. GDG1. ALIAS 



HISTORY 
RELEASE- 



RCVY-VOL- 



-333001 



RCVY-DEVT X ' 30502009 ' 



RCVY-CI X '000017' 



NONVSAM 

HISTORY 

OWNER-IDENT 
RELEASE 



MJK.NONVSAM1 



-(NULL) 
2 



CREATION 

EXPIRATION- 



-77.040 
-00.000 



RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 



RCVY-CI X '000018' 



Figure 22 (Part 1 of 2). An Example of LISTCAT HISTORY Output 
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CLUSTER MJKCAT 

HISTORY 

OWNER-IDENT ( NULL ) CREATION 77 . 040 

RELEASE 2 EXPIRATION 99.999 

DATA VSAM.CATALOG.BASE.DATA. RECORD 

HISTORY 

OWNER-IDENT (NULL ) CREATION 00 . 000 

RELEASE <- 2 EXPIRATION 00.000 

INDEX VSAH. CATALOG. BASE. INDEX. RECORD 

HISTORY 

OWNER-IDENT (NULL) CREATION 00.000 

RELEASE 2 EXPIRATION 00.000 

VOLUME 333001 

HISTORY 

RELEASE 2 RCVY-VOL 333001 RCVY-DEVT X' 30502009' RCVY-CI X* 000009' 

LISTING FROM CATALOG ~ MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GDG 1 

INDEX 3 

NONVSAM 2 

PAGESPACE r--0 

PATH 1 

SPACE 1 

USERCATALOG 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 22 (Part 2 of 2). An Example of LISTCAT HISTORY Output 
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LISTCAT CREATION/EXPIRATION OUTPUT LISTING 



When you specify the LISTCAT command and include the CREATION or 
EXPIRATION parameter (or both) , entries that have a creation or 
expiration date are selected according to the number of days you 
specify in the subparameter . 

In Figure 23, for example, because all entries in the listed 
catalog, MJKCAT, were created on the same day as the LISTCAT, no 
entries are listed as a result of the LISTCAT CREATI0N(5) job. 
When that job is run on an older catalog, each entry whose 
creation date is previous to the number of days specified with 
the CREATION parameter is listed (that is, the CREATION number 
of days specifies that all objects in the catalog at least 5 
days old are to be listed). The creatidn date of the data and 
index objects of a cluster or alternate index is always the same 
as the creation data of its associated cluster or alternate 
index object. The creation date of the data and index object of 
a catalog is always set to 0. 

When you list all entries of a catalog, and you specify the 
CREATION parameter, each user catalog connector entry and each 
alias entry are also listed regardless of their creation date. 

When the LISTCAT EXPIRATION(20 ) job is run, each entry whose 
expiration date occurs within 20 days of today's date is listed. 
Because the expiration date of a cluster or alternate index is 
controlled by the cluster or alternate index object entry in the 
catalog, the expiration date for the data and index objects of a 
cluster or alternate index is always 0. 

When you list all entries of a catalog and you specify the 
EXPIRATION parameter, each volume entry will be listed because 
volume entries have no expiration date. 

These types of entries can have a creation or expiration date: 
ALTERNATEINDEX, PATH, CLUSTER, DATA, INDEX, NONVSAM, GDG, and 
PAGESPACE. 



/* LIST EACH CATALOG ENTRY WHOSE CREATION DATE */ 
/* IS 5 DAYS AGO OR GREATER (THAT IS, THE OBJECT */ 

/* IS AT LEAST 5 DAYS OLD). */ 

LISTCAT - 

CREATI0N(5) - 
CATALOG(MJKCAT) 

LISTING FROM CATALOG — MJKCAT 

ALIAS MJK.GDG1. ALIAS 

Figure 23 (Part 1 of 2). An Example of LISTCAT CREATION/EXPIRATION Output 
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LISTING FROM CATALOG— MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 
AIX 

ALIAS -1 

CLUSTER — 

DATA • — — 

GDG 

INDEX 

NONVSAM 

PAGESPACE 

PATH 

SPACE . Q 

USERCATALOG ■ 

TOTAL • — 1 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

/* LIST EACH CATALOG ENTRY WHOSE EXPIRATION DATE */ 

/* IS WITHIN 20 DAYS 

LISTCAT - 

EXPIRATIONC20) - 
CATALOG(MJKCAT). 



LISTING FROM CATALOG — MJKCAT 



AIX MJK.ALT.INDEX1 

DATA MJK. ALT. INDEX1. DATA 

INDEX MJK. ALT. INDEX1. INDEX 

PATH MJK. AIX1. PATH 

ALIAS MJK. GDG1. ALIAS 

NONVSAM MJK.NONVSAM1 

VOLUME 333001 

LISTING FROM CATALOG — MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX — 1 

ALIAS — 1 

CLUSTER 

DATA 1 

GDG .___ 

INDEX 1 

NONVSAM 1 

PAGESPACE 

PATH — — 1 

SPACE ■ 1 

USERCATALOG 

TOTAL 7 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 23 (Part 2 of 2). An Example of LISTCAT CREATION/EXPIRATION Output 

436 0S/VS2 Access Method Servi ces 



EXAMPLES OF LISTCAT IN A TSO ENVIRONMENT 



The following examples illustrate the output produced at a TSO 
terminal for LISTCAT NAMES (default) and LISTCAT VOLUME. A TSO 
logon ID of IBMUSER is assumed. 

For LISTCAT NAMES, the catalog name is printed followed by the 
names of all entries that have a high-level qualifier equal to 
the USER logon ID. 

For LISTCAT VOLUME, all entrynames that have a high-level 
qualifier equal to the USER logon ID are printed followed by the 
volume serial numbers for those entries that contain volume 
i nf ormat i on . 

Note: Because volume serial numbers for a cluster or an 
alternate index are contained in the data and index components, 
the data and index must have been named on the initial DEFINE in 
order to list the volume serial numbers. 

LOGON IBMUSER 



READY 
LISTCAT 

IN CATALOG: AMASTCAT 
IBMUSER. AIX 
IBMUSER. AIXDATA 
IBMUSER. AIXIDX 
IBMUSER. GDG 
IBMUSER. GDG. G0001V00 
IBMUSER. GDG. G0002V00 
IBMUSER. GDG. G0003V00 
IBMUSER. KSDS 
IBMUSER. KSDSDATA 
IBMUSER. KSDSIDX 
IBMUSER. NVSAM1 
IBMUSER. NVSAM2 
IBMUSER. NVSAM3 
IBMUSER. NVSAM4 
IBMUSER. NVSAM5 
READY 

LISTCAT VOLUME 

IBMUSER. AIX 
IBMUSER. AIXDATA 

— VOLUMES — 
333001 

IBMUSER. AIXIDX 

— VOLUMES — 
333001 

IBMUSER. GDG 
IBMUSER. GDG. G0001V00 

— VOLUMES— 
333001 
333002 
333003 

IBMUSER. GDG. G0002V00 
—VOLUMES — 

333004 

333005 

333006 

333007 

333008 
IBMUSER. GDG. G0003V00 

— VOLUMES — 
333009 
333010 
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IBMUSER.KSDS 
IBMUSER.KSDSDATA 

— VOLUMES — 
333001 

IBMUSER.KSDSIDX 

— VOLUMES — 
333001 

IBMUSER.NVSAM1 

— VOLUMES — 
231401 
231402 

IBMUSER.NVSAM2 

— VOLUMES — 
231403 
231404 
231405 

IBMUSER.NVSAM3 

— VOLUMES — 
231406 

IBMUSER.NVSAM4 

— VOLUMES — 
231407 

IBMUSER.NVSAM5 

— VOLUMES — 
231408 
231409 
231410 
231411 
231412 

READY 
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APPENDIX C. JCL DP PARAMETERS TO TAKE CARE WITH 



Because OS/VS does not disallow any DD statement parameters and 
subparameters for VSAM, you should be aware of the 
specifications that either do nothing in a VSAM environment or 
might cause problems for you. Figure 24 shows the DD statement 
parameters and subparameters to be avoided with VSAM. 



Parameter Subparameter 
AFF ddname 



CHKPT 



DATA 



DCB 



EOV 



All 



DISP 



CATLG 

DELETE 

MOD 

KEEP 
NEW 



Comment 

You must use this parameter carefully. If 
the cluster components, the data and its 
index, reside on unlike devices* the results 
of an AFF specification are unpredictable. 

Because checkpoints at end of volume are 
executed only for BSAM and QSAM data sets, 
this parameter does not apply to VSAM data 
sets and need not be coded. 

Because there is no way to get VSAM data into 
the input stream, this parameter is not 
applicable to VSAM. 

The access-method control block (ACB), not 
the DCB, describes VSAM data sets; therefore, 
the DCB parameter is not applicable to VSAM. 
An access-method control block is generated 
by an ACB or GENCB macro, and can be modified 
by a MODCB macro. 

CATLGVSAM data sets are cataloged and 
uncataloged as a result of an Access Method 
Services command; if CATLG is coded, a message 
is issued, but the data set is not cataloged. 

VSAM data sets are deleted as a result of an 

Access Method Services command; if DELETE is 

coded, a message is issued, but the data set 
is not deleted. 

For VSAM data sets, MOD is treated as if OLD 
were specified, except for processing with an 
ISAM program, in which case MOD indicates 
resume load. 

Because KEEP is implied for VSAM data sets, 
it need not be coded. 

VSAM data spaces are initially allocated as 
a result of the Access Method Services 
DEFINE command. If NEW is specified, OS/VS 
also allocates space, and it is never used 
by VSAM. Moreover, an Access Method Services 
request for space may fail if the DISP=NEW 
acquisition of space causes too little space 
to remain available. 



Figure 24 (Part 1 of 3). JCL DD Parameters 
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Parameter Subparameter 
UNCATLG 



DSNAME 



LABEL 



LABEL 



SEP 



SPACE 



dsname(areaname) 
dsnameC gene rati on) 

dsname(member) 

All temporary 
dsnames 



All backward 
DD references 
of the form 
^ . ddname 

BLP, NL, NSL 



IN 



OUT 



NOPWREAD 



PASSWORD 



SL, SUL 



ddname 



Comment 

VSAM data sets are cataloged and uncataloged 
as a result of Access Method Services commands; 
if UNCATLG is coded, a message is issued, but 
the data set is not uncataloged. 

The name is used; areaname is ignored. 

A generation data group entry must exist in 
the VSAM catalog for this to apply. 

The name is used; member is ignored. 

Because VSAM data sets are built by Access 
Method Services, which uses the data-set 
name supplied in the DEFINE command; 
temporary names cannot be used with VSAM. 

If the object referred to i s a cluster and 
the data set and index reside on unlike 
devices, the results of a backward DD ' 
reference are unpredictable. 

Because these subparameters have no meaning 
for direct-access devices, they do not apply 
for VSAM data sets, which all reside on 
direct-access storage. 

Because IN is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, IN does not apply. 

Because OUT is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, OUT does not apply. 

The password-protection bit is set for all 
VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL 
parameter. 

The password-protection bit is set for all 
VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL 
parameter. 

Although these parameters apply to 
direct-access storage device's, SL is always 
used for VSAM, whether you specify SL, SUL, 
or neither. 

You must use this parameter carefully. If 
the cluster components, the data and its 
index, reside on unlike devices, the results 
of a SEP specification are unpredictable. 

VSAM data spaces ar& initially allocated as 
a result of the Access Method Services 
DEFINE command. If SPACE is specified, 
therefore, an extent is allocated that is 
never used by VSAM. Moreover, an Access 
Method Services request for space may fail 
as a result of the SPACE acquisition of space. 



Figure 24 (Part 2 of 3). JCL DD Parameters 



440 0S/VS2 Access Method Services 



Parameter Subparameter 
SPLIT 



SUBALLOC 



SYSOUT 



UCS 



UNIT 



VOLUME 



All 



AFF 



SEP 



REF 



volseqft 
volcount 



Comment 

VSAM data spaces are initially allocated as 
a result of the Access Method Services 
DEFINE command. If SPLIT is specified, 
OS/VS also allocates space, and it is never 
used by VSAM. Moreover, an Access Method 
Services request for space may fail If the 
SPLIT acquisition of space causes too little 
space to remain available. 

VSAM data spaces are initially allocated as 
a result of the Access Method Services 
DEFINE command. If SUBALLOC is specified, 
OS/VS also allocates space, and it is never 
used by VSAM. Moreover, an Access Method 
Services request for space may fail if the 
SUBALLOC acquisition of space causes too little 
space to remain available. If the data set for 
which SUBALLOC is specified /is a VSAM data set, 
the request is denied. 

If SYSOUT is coded with a mutually exclusive 
parameter (for example, DISP), the job step 
is terminated with an error message. 

Because this parameter applies only to 
unit-record devices, it does not apply to VSAM. 

You must use this subparameter carefully. 
If the cluster components, the data and its 
index, reside on unlike devices, the results 
of UNIT=AFF are unpredictable. 

You must use this subparameter carefully. 
If the cluster components, the data and its 
index, reside on unlike devices, the results 
of UNIT=SEP are unpredictable. 

You must use this subparameter carefully. 
If the referenced volumes are not a subset 
of those contained in the catalog record 
for the data set, the results are 
unpredi ctable. 

Results are unpredictable. 

This subparameter is used to request some 
number of nonspecific volumes. Because all 
VSAM volumes must be specifically defined 
before processing, volcount is not applicable 
to VSAM data sets. 



Figure 24 (Part 3 of 3). JCL DD Parameters 
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APPENDIX D. INTERPRETING LISTCRA OUTPUT LISTINGS 



When you code the LISTCRA command, you can specify options that 
allow you to tailor the contents of the LISTCRA output. This 
appendix illustrates the various types of the LISTCRA output* 
the order in which entries are listed* and the meanings of the 
1 i sted f i elds. 

There are five types of LISTCRA listings. Four of the types are 
illustrated in this appendix. The fifth type, SEQUENTIALDUMP, is 
exactly the same as the DUMP NOCOMPARE type except that the 
entries are not sorted into groups. 

Each listed entry is identified by type (that is, cluster* 
nonVSAM, etc.) and by name . Entries are usually listed in 
alphabetic order within groups of entries, according to 
entryname (except for SEQUENTIALDUMP) . However, if insufficient 
virtual storage is available for the sorting operation, the 
records are listed as they appear in the catalog recovery area. 

On the listing, entries are sorted into three groups (except for 
a SEQUENTIALDUMP listing): 

• VSAM entries (which are also sorted according to entryname). 
Cluster entries, alternate index entries, and their 
associated data, index, and path entries are within this 
group. 

• Other entries that are sorted according to entryname. User 
catalog connector entries and nonVSAM entries are in this 
group. 

• Unsorted entries* other entries that are not sorted 
according to entryname. Entries that are listed within this 
group depend on the type of LISTCRA listing requested. 

The following list contains the abbreviation, type, and 
description for each kind of entry that can be listed as a 
result of the LISTCRA command* 

Description 

Alternate index entry 

Alias entry 

Cluster entry 

Data component entry 

Freespace entry 

Generation data group entry 

Index component entry 

NonVSAM data set entry 

Extension record for an entry other than 
a volume entry 

Path entry 

User catalog connector entry (in the 
master catalog only) 

Upgrade set entry 



Abbreviation 


Type 


AIX 


G 


ALIA 


X 


CLUS 


c 


DATA 


D 


FRSP 


F 


GDGB 


B 


INDX 


I 


NONV 


A 


OEXT 


E 


PATH 


P 


UCAT 


U 



UPGD 
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Abbreviation Type Description 

VEXT W Extension record for a volume entry 

VOL V Volume entry 



EXAMPLES OF LISTCRA LISTINGS 



The five types of LISTCRA listings are' 

• NAME NOCOMPARE — This is the default option. Each entryname, 
its volumes* and the name and volumes of each related entry 
are listed. Within the "unsorted entries" group, all catalog 
records not yet printed are printed. See Figure 25. 

• DUMP NOCOMPARE — When DUMP is specified (NOCOMPARE is a 
default), each record is listed in the dump format. In 
addition, the name and volumes of each indirectly related 
entry are also listed. Within the "unsorted entries" group, 
the CRA's self-describing records (control intervals through 
8) are printed, and any free space records and records not 
yet printed are printed. See Figure 26. 

• NAME COMPARE — When COMPARE is specified (NAME is a default), 
only the name of each miscompared catalog entry is listed. A 
miscompared catalog entry is one whose information is not 
identical to the information contained in the entry's copy 
in the catalog recovery area. A MISCOMPARE message is 
printed that identifies the most serious level of 

mi scompari son . Within the "unsorted entries" group, 
miscompared records not yet printed out are printed. See 
Figure 27. 

•• DUMP COMPARE — When DUMP and COMPARE are specified, only the 
records (in dump format) of each miscompared catalog entry 
are listed. A miscompared catalog entry is one whose 
information is not identical to the information contained in 
the entry's copy in the catalog area. For each entry, the 
catalog recovery area copy is listed first, followed by the % 
catalog entry, followed by a line that contains asterisks to 
identify each miscompared byte. Following each entry, a 
MISCOMPARE message is printed that identifies the most 
serious level of mi scompari son . Within the "unsorted 
entries" group, miscompared records not yet printed out are 
printed in the dump format. See Figure 28. 

Note: As explained above, all MISCOMPARE messages result 
from a comparison between the catalog and the CRA if the 
comparison shows that the catalog and CRA records are not 
identical. No inference is intended as to which is correct. 
You must make this determination yourself by looking at 
other mismatches in the same listing and by examining 
related records in the catalog or CRA. 

• SEQUENTIALDUMP — When SEQUENTIALDUMP is specified, each 
record in the catalog recovery area is printed. The format 
of the output is the same as the DUMP NOCOMPARE format, 
except that the entries are not sorted into groups or 
alphabetic sequence. 

See 0S/VS2 Catalog Management for a complete description of 
catalog recovery area record formats, catalog record 
formats, and relationships between catalog records. 
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JOB CONTROL LANGUAGE (JCL) FOR LI5TCRA JOBS 



The job control language (JCL) statements that can be used to 
list catalog recovery areas are 1 

//LISTCAT JOB 
//STEP1 EXEC PGM=IDCAMS 
//STEPCAT DD DSN=YOURCAT,DISP=SHR 
//CATDD DD DSN=YOURCAT,DISP=OLD 
//CRADD1 DD VOL=SER=333001,UNIT=3330,DISP=OLD 
//CRADD2 DD VOL=SER=333002,UNIT=3330 ,DISP=0LD 
//OUTDD DD DSN=LISTCRA. OUTPUT, UNIT=2400-3, 
// VOL =SER = TAP El 0, L ABEL = (1,NL),DISP = ( NEW, KEEP), 

// DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 
LISTCRA - 

COMPARE - 

DUMP - 

INFILE(CRADD1,CRADD2) - 

CATALOGCYOURCAT/PASSWORD CATDD) - 

MASTERPW(SECRET) - 

OUTFILE(OUTDD) 
/* 

The JOB statement contains user and accounting information 
required for your i nstallati on. 

The EXEC statement identifies the program to be executed, IDCAMS 
(that is, the Access Method Services program). 

• STEPCAT DD, which allocates your catalog. This is only 
required if the COMPARE option is specified. The catalog 
must be open as a catalog before it can be opened as a data 
set through the DD card that so identifies it for the 
compar i sons. 

• CATDD, which specifies the catalog to be opened as a data 
set and compared to the catalog recovery areas. This is only 
required if the COMPARE option is specified. 

• CRADD1, which specifies a volume whose catalog recovery area 
(CRA) i s to be listed. 

• CRADD2, which specifies another volume whose CRA i s to be 
1 i sted. 

• OUTDD, which specifies an alternate output file, so that the 
LISTCRA output can be written onto an auxiliary storage 
device. The LISTCRA command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCRA output is written 
to the alternate output device. JCL statements, system 
messages, and job statistics are written to the SYSPRINT 
output devi ce. 

DSN=LISTCRA. OUTPUT specifies the name for the magnetic 
tape file. 

UNIT=2400-3 and VOL=SER=TAPE10 specifies that the file 
is to be contained on magnetic tape volume TAPE10. 

LABEL=(1,NL) specifies that this is the first file on a 
nonlabeled tape. You can also use a standard-labeled 
tape by specifying LABEL=( 1 , SL) . If subsequent job steps 
produce additional files of LISTCRA output on the same 
tape volume, you should increment the file number in 
each job step's LABEL subparameter (that is, 
LABEL=(2,NL) for the second job step, LABEL=(3,NL) for 
the third job step, etc.). 

DISP=(NEW,KEEP) specifies that this is a new tape file 
and is to be rewound when the job finishes. If a 
subsequent job step prints the tape, DISP=(NEW,PASS) 
should be specified. If your job step contains more than 
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one LISTCRA command, DISP=(M0D, KEEP) or DISP=CM0D, PASS) 
can be used to concatenate all of the LISTCRA output in 
one sequential file. 

DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) specifies that the 
LISTCRA output records are vari able-length> blocked 
5-to-l, and c\re preceded by an ANSI print-control 
character . 

• SYSPRINT DD, which is required for each Access Method 
Services job step. It identifies the output queue, SYS0UT=A, 
on which all LISTCRA output and system output messages are 
printed (unless the OUTFILE parameter and its associated DD 
statement is specified — see OUTDD above). 

Note : If you want a 11 output to be written to an auxiliary 
storage device, replace 'OUTDD' with 'SYSPRINT' in the OUTDD DD 
statement and omit the SYSPRINT DD SYS0UT=A statement. 

• SYSIN DD, which specifies, with an asterisk (*), that the 
statements that follow are the input data statements. A '/*' 
terminates the input data statements. 

The LISTCRA command parameters shown above are common to the 
LISTCRA DUMP COMPARE example that follows. Other LISTCRA 
parameters may be coded and the output that results is 
i llustrated. 

COMPARE, which specifies that the CRA entries are to be compared 
with the catalog entries identified by the CATALOG parameter. 
Only those that mi scompare will be listed. 

DUMP, which specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 

INFILE, which specifies the two DD statements, CRADD1 and 
CRADD2, which identify the two volumes whose CRA's are to be 
compared with the catalog entries and the miscomparing entries 
listed. 

CATALOG, which identifies the DD statement, CATDD, which 
identifies the catalog, YOURCAT, whose entries are to be 
compared with those in the CRAs. If the catalog is password 
protected, its master password, PASSWORD, is required. 

MASTERPW, which specifies the master password of the master 
catalog, SECRET, to enable the CRAs to be OPENed. 

OUTFILE, which points to the OUTDD DD statement. The OUTDD DD 
statement allocates an alternate output file for the LISTCRA 
output . 

If you want to print the LISTCRA output that is contained on an 
alternate output file, you can use the IEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCRA. OUTPUT, that was allocated previously: 

//PRINTOUT JOB 

//STEP1 EXEC PGM=IEBGENER 

//SYSUT1 DD DSN=LISTCRA.OUTPUT,UNIT=2400-3, 

DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSUT2 DD SYS0UT=A 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD DUMMY 
/* 
// 
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LISTCRA OUTPUT LISTING 



When you specify LISTCRA without any parameters* each entryname, 
its volume(s), and the name and volume(s) of each related entry 
are listed. The same listing would result if the NAME and 
NOCOMPARE parameters were specified. 

You can use this type of listing to list the name of each 
catalog entry whose copy is in the catalog recovery area, and to 
determine the number of entries in each catalog recovery area. 
The total number of entries is an approximate size, in records, 
of the catalog recovery area. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME ~ 333301 — VSAM ENTRIES 

VOL - 333301 

CRAVOLRCD - 10/07/74 23:35:00 

F4DSCBVSAM - 10/07/74 23:35:00 

F4DSCBDUMP - 10/07/74 23=35:00 

CLUS - AA.LISTCRA.ESDS 

DATA - TF41C9A0.VSAMDSET.DFD74280.T861DAD4.TF41C9A0 
DATA VOL - 
333301 

AIX - AA2.LR.ESDS 
DATA VOL - 

333301 

INDX VOL - 

333301 

AIX - AA1.LR.ESDS 
DATA VOL - 

333301 

INDX VOL - 

333301 

PATH - AAU.LR.ESDS 

UPGD - 

CLUS - AA.LISTCRA.KSDS 

DATA - T5C55DD0.VSAMDSET.DFD74280.T861DB0A.T5C55DD0 
DATA VOL - 
333301 

INDX - T5C56E70.VSAMDSET.DFD74280.T861DB0A.T5C56E70 
INDX VOL - 
333301 

AIX - AA1.LR.ESDS 

DATA - TCD41020.VSAMDSET.DFD74280.T861DB23.TCD41020 
DATA VOL - 
333301 

INDX - TCD41F00.VSAMDSET.DFD74280.T861DB23.TCD41F00 
INDX VOL - 
333301 

CLUS - AA.LISTCRA.ESDS 

PATH - AA1U.LR.ESDS 

PATH - AA1N.LR.ESDS 

CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TF081480 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 
INDX VOL - 
. 333301 
333301 

Figure 25 (Part 1 of 2). An Example of LISTCRA NAME NOCOMPARE Output 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 — OTHER ENTRIES 

UCAT - USERCAT2 

DATA VOL - 

333304 

NUMBER OF ENTRIES PROCESSED 
CLUS - 3 
DATA - 4 
AIX - 1 
INDX - 2 
PATH - 3 
VOL - 1 
UPGD - 1 
SUM - 15 

LISTCRA NAME NOCOMPARE Output Notes: 

1. Volume serial number 

2. Identifies the group that the following entries are within (in this case, 
VSAM Entri es) . 

3. The time stamps* 

CRAVOLRCD is the timestamp of the CRA volume record. It is updated only 
when the first catalog record and first CRA volume record are updated, 
after the CRA is opened when VSAM is running under OS/VS. (Note: If the 
volume is moved to a DOS/VS system and used there, the CRAVOLRCD timestamp 
is updated each time the catalog and CRA volume records are updated for a 
space allocation change.) 

F4DSCBVSAM is a timestamp in the format-4 DSCB, and is updated in the same 
manner as the CRAVOLRCD timestamp. 

F4DSCBDUMP is a timestamp in the format-4 DSCB, and is updated in the same 
manner as the CRAVOLRCD timestamp. It is also updated whenever the OS/VS 
utility program IEHDASDR dumps the volume. 

4. VSAM entries are listed along with the entryname and volume(s) of each 
related entry. 

5. Paths are shown as related only to the entry that the path provides access 
to. A path that serves as an alias for a VSAM data set is listed with the 
data-set's entry. A path that shows the relationship of an alternate index 
to a base cluster is listed with the alternate-index's entry only. 

6. UPGD indicates that there are alternate indexes in the base-cluster's 
upgrade set. If you want to identify the indexes in the upgrade set, use 
the DUMP NOCOMPARE option. 

7. The high-key value of each key range is shown. 

8. SUM is the total number of catalog recovery area entries printed. 
Figure 25 (Part 2 of 2). An Example of LISTCRA NAME NOCOMPARE Output 
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LISTCRA DUMP OUTPUT LISTING 



When you specify LISTCRA with the DUMP parameter, each record in 
the catalog recovery area is listed in dump format. In addition, 
the name and volumes of each indirectly related entry are also 
listed. The same listing would result if the DUMP and NOCOMPARE 
parameters were specified. 

When you specify LISTCRA SEQUENTIALDUMP , the same listing 
results — except that the. records are listed in their entry 
sequence within the catalog recovery area. 

You can use this type of listing to list the complete contents 

of each catalog entry whose copy is in the catalog recovery 

area, and to determine the exact number of entries and records 
in each catalog recovery area. 
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VOL - 333301/^J 

|000009| O flOO0OOC| OlF3F3F3 F3FOF10o\o0093050 
0020 00000000 00000000 000O00Oolii5frlBDO0 
0040 00000000 00000000 00000000 00000000 
0060 1152A820 00305020 09000032 E6019B00 
0080 00000000 2600003E 00000000 000D8500 
00A0 86000100 00378800 01000037 88000200 
OOCO 05000037 88000600 00480800 07000037 
OOEO 00378800 0B000037 88000COO 00378800 
0100 88001000 00378800 11000037 88001200 
0120 1500003E 88001600 003E8800 1700003E 
0140 003E8800 1B0O00O0 08001COO 000C0800 
0160 08002000 003C0800 21000C00 0051861D 
0180 46000COO 005486 1D B2050000 47O0OC0O 
01A0 B23F0000 4C0OOC0O 0058861D B23F0000 
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J 9 

2 00fB61D 



00000000 
13336DBF 
0100000E 
00378800 
88000800 
0D000037 
00378800 
88001800 
1D000018 
B1D60000 
0055861D 
50000C00 



D 8A4E0000 00000000 00000000 . 1333 30 Hi ■* <£ 

... . . .fTvt . - 333: 



7 EJF3F3F3 F3F0F100I 



00000000 
BF380002 
85000200 
03000037 
00378800 
88000EOO 
1300003E 
003E8800 
08001 EOO 
42000C00 
B2050000 
006086 1D 



00000000 00000000 
00000000 00861DEE 
00000500 00000000 
000F8500 03000037 
88000400 00378800 
09000037 88000A00 
00378800 0F000037 
88001400 003E8800' 
1900003E 88001A00 
00240800 1F000030 
0052861D B1D60000 
48000COO 0057861D 
B79C0000 2C1DB173 



©— 



CLUS - KSDS01 
OOOOOE 0000001 



0020 
0040 
0060 
0080 



01F3F3F3 F3F0F100 000E3050 
00000000 00000000 00000000 C300A800 
40404040 40404040 40404040 40404040 
FFFFFFFF FF74280F OOOOOFOO 00000000 
0200000C 02030000 12020400 00004401 



f 

i*6 8A4 



*, 



OOAO l 001A0006 C700001B 00000000 00000000 

DATA - T188D0C0.VSAMDSET.DFD74280.T861D99E.T188D0C0 



2 00986 »D 8A4E0000 00000000 00000000 p33301| . ... 6 + . . . 

6 CJD2E2C4 E2F0F140'| 40404040 40404040 C. . . (KSDS01 

40404040 40404040 40404040 40FFFFFF 

00070000 OOCOOOOO 00000201 00006024 

0006C400 00180006 C9000019 0006D900 D ] 

00000000 00000000 OOCOOOOO 00000000 G 



OOOOOD 


00000018 


01F3F3F3 


F3F0F100 


000D3050 


2009861D 


3A4E861D 


99E20000 


OOOOOOOO 


0020 


00000000 


00000000 


00000000 


C4016200 


8FE3F1F8 


F8C4F0C3 


F04BE5E2 


C1D4C4E2 


0040 


C5E34BC4 


C6C4F7F4 


F2F8F04B 


E3F8F6F1 


C4F9F9C5 


4BE3F1F8 


F8C4F0C3 


FOFFFFFF 


0060 


FFFFFFFF 


FF74280F 


00000000 


20000000 


22000000 


01000001 


80000000 


00000030 


0080 


OOOOOOOF 


F90000FF 


FFFFFFFF 


FFFFFFOO 


OOOOOOOO 


06000000 


COOOOOOO 


00010100 


OOAO 


00620201 


0000A902 


02000068 


03010000 


00440100 


62608000 


60000000 


03001400 


OOCO 


00000300 


00000000 


00000010 


OOOOOOOF 


F9000000 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOEO 


00000000 


00000000 


00000000 


OOOOOOOO 


01000000 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


0100 


00000000 


00000030 


00000000 


OOOOOOOO 


OOOOOOOO 


000006C3 


00001703 


27305020 


0120 


09F3F3F3 


F3F0F100 


00800100 


OOOOOOOO 


OOOOOOOO 


00300000 


00100000 


03000140 


0140 


00010000 


00000014 


00010002 


00000002 


00000001 


OOOOOOOO 


00002FFF 


0006E800 


0160 


00150000 


00000000 


00000000 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


INDX 


- T188E190.VSAMDSET.DFD74280.T861D99E.T188E190 






OOOOOF 


00000019 


01F3F3F3 


F3FOF100 


000F3050 


2009861D 


8A4E861D 


99E20000 


OOOOOOOO 


0020 


00000000 


00000000 


00000000 


C9015700 


8FE3F1F8 


F8C5F1F9 


F04BE5E2 


C1D4C4E2 


0040 


C5E34BC4 


C6C4F7F4 


F2F8F04B 


E3F8F6F1 


C4F9F9C5 


4BE3F1F8 


F8C5F1F9 


FOFFFFFF 


0060 


FFFFFFFF 


FF74280F 


00000000 


2000FFFF 


FFFFOOOO 


01000001 


80000000 


00000028 


0080 


OOFFFFFF 


FFOOOOFF 


FFFFFFFF 


FFFFFFOO 


OOOOOOOO 


05000000 


COOOOOOO 


00010100 


OOAO 


00620201 


00006803 


01000000 


44010062 


60000060 


00010003 


00140000 


00140000 


OOCO 


00000000 


00000200 


000001F9 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOEO 


00000000 


00000000 


00000001 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


OOOOOOOO 


0100 


00002800 


00000000 


OOOOOOOO 


OOOOOOOO 


0006C300 


00170327 


30502009 


F3F3F3F3 


0120 


F0F10000 


80010000 


00000000 


OOOOOOOO 


28000000 


02000014 


00140000 


02000000 


0140 


00001400 


01000200 


01000200 


01000100 


OOOOOOOO 


0027FF00 


OOOOOOOO 


OOOOOOOO 


PATH 


- PATH01 

















000010 0000001 A 
0020 OOOOOOOO 
0040 40404040 
0060 FFFFFFFF 
0080 0200000C 



01F3F3F3 F3FOF100 00100000 
OOOOOOOO OOOOOOOO D9009800 
40404040 40404040 40404040 
FF74280F OOOOOF80 OOOOOOOO 
02030006 C3000017 0006C400 



0000861D 8A4EOOO0 OOOOOOOO OOOOOOOO 
6CD7C1E3 C8F0F140 40404040 40404040 
40404040 40404040 40404040 40FFFFFF 
OOOOOOOO OOCOOOOO 00000201 00000602 
00180006 C9000019 OOOOOOOO OOOOOOOO 



333301 £ + ...S 

D T188D0C0.VSAMDS 

ET.DFD74280.T861D99E.T188D0C0. . . 



333301 £ + . . .S 

I T188E190.VSAMDS 

ET.DFD74280.T861D99E.T188E190. . . 



.C £..3333 



.R. . . (PATH01 



Figure 26 (Part 1 of 2). An Example of LISTCRA DUMP NOCOMPARE Output 
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AIX - AIX01 
DATA VOL - 

333301 
INDX VOL - 

333301 

UPGD - 

000014 0000001 
0020 0000001 
0040 01000, 




00 00143050 

0000000 E8004B00 

00000000 



200086 ID 8A4E000O 
31000000 00000200 
00000000 00000000 



DATA - TF081480.VSAMDSET.DFD74280.T861DBOE.TF081480 



000038 
0020 
0040 
0060 
0080 
OOAO 
00C0 
OOEO 
0100 
0120 
0140 
0160 
0180 
01AO 
01C0 



00000048 
00000000 
C5E34BC4 
FFFFFFFF 
00000000 
00620201 
00001400 
00000000 
00000000 
09F3F3F3 
0018000A 
00040003 
00000000 
C1C6C100 
0000004F 



01F3F3F3 
00000000 
C6C4F7F4 
FF74280F 
500000FF 
00006803 
00000000 
00000000 
00000050 
F3F0F1OO 
C1C1C1C1 
00040001 
00002800 
0AC1C1C1 
FF00OOOO 



F3F0F1O0 
00000000 
F2F8F04B 
00000000 
FFFFFFFF 
010000BD 
00000002 
00000000 
00000000 
00800100 
C1C1C1C1 
00000000 
00005000 
C1C1C1C1 
00000000 



00383050 
C401C500 
E3F8F6F1 
20000000 
FFFFFFOO 
03020000 
00000000 
00000000 
00000000 
00000000 
C1C1000A 
000027FF 
00000200 
C1E9E900 
00000000 



200986 1D 
8FE3C6F0 
C4C2F0C5 
06000000 
00000000 
00440100 
5000POOO 
02000000 
00000000 
00000000 
C1C1C1C1 
03273050 
00140009 
14000100 
00000000 



8A4E861D 
F8F1F4F8 
4BE3C6F0 
01000001 
06000000 
62608400 
00000000 
00000000 
000006C3 
00280000 
C1C1C1C1 
2009F3F3 
40001800 
03000500 
00000000 



00000000 

oooocooo 

00000000 



BOFOOOOO 
F04BE5E2 
F8F1F4F8 
80000000 
COOOOOOO 
60000000 
00000000 
00000000 
00004703 
00020000 
C5F90014 
F3F3F0F1 
0AC1C1C1 
03000500 
00000000 



.333301 t + . 



00000002 
00000000 



•^•B*^- 



00000000 
C1D4C4E2 
FOFFFFFF 
00000050 
00010100 
OAOOOAOO 
00000000 
00000000 
27305020 
14000140 
09010003 



333301 t + ...0 

D.E. .TF081480.VSAMDS 

ET.DFD74280.T86TDB0E.TFO81480. . . 



J333301J 

AAAAAAAAAA. .AAAAA AAAE9. 

00008001 t. . |333302H 

C1C1C1C1 ( 

01000028 AFA..AAAAAAAAZZ 

00000000 



INDX - TF082370.VSAMDSET.DFD74280.T861DBOE.TF082370 



00003A 00000049 01F3F3F3 F3FOF100 003A3050 2009861D 8A4E861D BOFOOOOO 00000000 

0020 00000000 00000000 00000000 C90 18900 8FE3C6F0 F8F2F3F7 F04BE5E2 C1D4C4E2 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 C4C2F0C5 4BE3C6F0 F8F2F3F7 FOFFFFFF 

0060 FFFFFFFF FF74280F 00000000 2000FFFF FFFFOOOO 01000001 80000000 00000028 

0080 OOFFFFFF FFOOOOFF FFFFFFFF FFFFFFOO 00000000 06000000 COOOOOOO 00010100 

OOAO 00620201 00006803 010000A9 03020000 00440100 62600400 60000400 OAOOOAOO 

OOCO 00001400 00000000 00000002 00000001 F9000000 00000000 00000000 00000000 

OOEO 00000000 00000000 00000000 00000000 01000000 00000000 00000000 00000000 

C100 00000000 0.0000028 00000000 00000000 00000000 000006C3 00004703 27305020 

0120 09F3F3F3 F3FOF100 00800100 00000000 00000000 00280000 00020000 14000140 

0140 00190000 00000014 00010003 00060003 00060001 00000000 000027FF 03273050 

0160 2009F3F3 F3F3F0F1 00004000 00000000 00000000 00000000 00000200 00140001 

0180 40001900 00000000 00000000 00000000 00000000 00000000 00000000 00000000 



.333301 i + ...0 

I TF082370 . VSAMDS 

ET.DFD74280.T861DBOE.TF082370. . . 



LISTCRA DUMP NOCOMPARE Output Notes: 

Note: When you specify SEQUENTIALDUMP, the same information is listed, 
entries are not sorted according to type of entry, or according to 
alphameric-sequence of the entryname field. See also Note 7 below. 



The 



1. The 3-byte CRA control interval number, in hexadecimal form. 

2. The 3-byte control interval number of the catalog record for which this is 
a copy, in hexadecimal form. 

3. The entrytype at offset X'2C (decimal 44), a character that identifies the 
type of catalog entry being listed. 

4. A 44-byte field at offset X'31' (decimal 49) that contains the entry's 
entryname (padded with binary zeros), or an 8-byte field followed by 36 
bytes of binary zero that contains the volume entry's volume serial number. 

5. The volume serial number of the recovery volume. 

6. A 2-byte displacement value. Printing is suppressed after the last line 
containing data is listed, even though all catalog records are 512 bytes 
long. 

7. As in the NAME NOCOMPARE output, the alternate index name and the fact that 
there is an upgrade set is given, along with the volume serial numbers of 
the alternate index's data and index components. (Note: If SEQUENTIALDUMP 
is specified, the information described with this note is not listed.) 

8. The first byte identifies the alternate index's data component and the next 
three bytes contain its catalog control interval number. 

9. The first byte identifies the alternate index's index component and the 
next three bytes contain its catalog control interval number. 

10. Since there are two key ranges for this cluster, there are> two volume 
information sets of fields in the cluster's data and index component 
entri es. 

Figure 26 (Part 2 of 2). An Example of LISTCRA DUMP NOCOMPARE Output 
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LISTCRA COMPARE OUTPUT LISTING 



When you specify LISTCRA with the COMPARE parameter, each record 
in the catalog recovery area is compared to its original in the 
catalog. The name of each catalog entry that miscompares is 
listed. A mi scompared catalog entry is one whose information is 
not identical to the information contained in the entry's copy 
in the catalog recovery area. The same listing would result if 
the NAME and COMPARE parameters were specified. 

You can use this type of listing to determine the number of 
damaged entries in your catalog, and you can get an idea of the 
type of damage that occurred to each entry. You can issue the 
EXPORTRA and IMPORTRA commands to recover the catalog and make 
its damaged entries usable. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME ~ 333301 — VSAM ENTRIES 

CATVOLRCD - 09/17/42 23:53:47 

CRAVOLRCD - 10/07/74 23:35:00 

F4DSCBVSAM - 10/07/74 23:35:00 

F4DSCBDUMP - 10/07/74 23:35:00 

CLUS - LR. DELETED. ESDS 

* MISCOMPARES - CATALOG ENTRY HAS DIFFERENT NAME 

CLUS - LR.MCHURBA.ESDS 

DATA - T73FEDA0.VSAMDSET.DFD74280.T861DAE1.T73FEDA0 
DATA VOL - 
333301 

* MISCOMPARES - HIGH USED RBA 

CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TF081480 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

* MISCOMPARES - HIGH USED RBA 

INDX - TF082370.VSAMDSET.DFD74280.T861DBOE.TF082370 
INDX VOL - 
333301 
333301 

* MISCOMPARES - STATISTICS 

NUMBER OF ENTRIES PROCESSED 

CLUS - 23 

DATA - 18 

AIX - 8 

INDX - 11 

PATH - 5 

VOL - 1 

UPGD - 3 

SUM - 69 

IDC0665I NUMBER OF ENTRIES THAT MISCOMPARED IN THIS CRA - 3 

IDC0877I NUMBER OF RECORDS THAT MISCOMPARED IN THIS CRA - 4 

LISTCRA NAME COMPARE Output Notes: 

1. In addition to the timestamps described for the NAME NOCOMPARE output 
(noted previously), the timestamp in the catalog volume record, CATVOLRCD, 
is listed. CATVOLRCD is updated in the same manner as the CRAVOLRCD 
timestamp. 

2. The MISCOMPARES message always refers to the record listed above it. See 
"Regaining Access to Data" under "Catalog Recovery" in the chapter on Data 
Security and Protection for the cause and seriousness of this MISCOMPARES 
message. 

3. The number of records is sometimes larger than the number of entries, 
because an entry might consist of a catalog record and one or more 
extension records that failed to compare correctly. 

Figure 27. An Example of LISTCRA NAME COMPARE Output 
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LISTCRA DUMP COMPARE OUTPUT LISTING 



When you specify LISTCRA with the DUMP and COMPARE parameters, 
each record in the catalog recovery area is compared to its 
original in the catalog. Each catalog entry's copy in the 
catalog recovery area that mi scompares is listed* followed by 
its original catalog entry (which is damaged), followed by 
asterisks to indicate each miscompared byte. 

You can use this type of listing to determine the exact damage 
that occurred to each entry. You might be able to correct some 
or all of the damage by using the ALTER command. You can issue 
the EXPORTRA and IMPORTRA commands to recover the catalog and 
make its damaged entries usable. 



LISTING OF CATALOG RECOVERY AREA FOR VOLUME 



VSAM ENTRIES 



CLUS - LR.MCHURBA.ESDS 

000020 0000002C 01F3F3F3 F3F0F100 00203050 
CATRCD 0000002C 01F3F3F3 F3FOF100 00203050 

0020 00000000 00000000 00000000 C3008200 
00000000 00000000 00000000 C3008200 

0040 40404040 40404040 40404040 40404040 
40404040 40404040 40404040 40404040 

0060 FFFFFFFF FF74280F OOOOOFOO 00000000 
FFFFFFFF FF74280F OOOOOFOO 00000000 

0080 002DOOOO 00000000 00000000 00000000 
002D0000 00000000 00000000 00000000 



2009861D 8A4E0000 00000000 00000000 
2009861D 8A4E0000 00000000 00000000 

6CD3D94B D4C3C8E4 D9C2C14B C5E2C4E2 
6CD3D94B D4C3C8E4 D9C2C14B C5E2C4E2 

40404040 40404040 40404040 40FFFFFF 
40404040 40404040 40404040 40FFFFFF 

00000000 00020100 00004401 0006C400 
00000000 00020100 00004401 0006C400 

00000000 00000000 00000000 00000000 
00000000 00000000 00000000 00000000 



.333301 6 + . 

.333301 6 + . 



« 



.C. . . (LR.MCHURBA.ESDS 
.C. . . (LR.MCHURBA.ESDS 



DATA - T73FEDAO.VSAMDSET.DFD74280.T861DAE1 .T73FEDA0 



000021 0000002D 01F3F3F3 F3F0F100 00213050 
CATRCD 0000002D 01F3F3F3 F3F0F100 00213050 

0020 00000000 00000000 00000000 C4015700 
00000000 00000000 00000000 C4015700 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 
C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 

0060 FFFFFFFF FF74280F 00000000 20000000 
FFF FFFFF FF74280F 00000000 20800000 
* ** 

0080 00000000 500000FF FFFFFFFF FFFFFFOO 
00000000 500000FF FFFFFFFF FFFFFFOO 

00A0 00620201 00006803 01000000 44010062 
00620201 00006803 01000000 44010062 



2009861D 8A4E861D AE2E0000 00000000 
200986 1D 8A4E861D AE2EOO0O 00000000 

8FE4F7F3 C6C5C4C1 F04BE5E2 C1D4C4E2 
8FE4F7F3 C6C5C4C1 F04BE5E2 C1D4C4E2 

C4C1C5F1 4BE3F7F3 C6C5C4C1 FOFFFFFF 
C4C1C5F1 4BE3F7F3 C6C5C4C1 FOFFFFFF 

04000000 01000001 80000000 00000028 
04000000 01000001 80000006 00000028 

** 
00000000 05000000 00000000 00010100 
00000000 05000000 C0000000 00010100 

60000060 00000000 00000000 00140000 
60000060 00000000 00000000 00140000 



.333301 6 + . 

.333301 6 + . 



.D T73FEDAO.VSAMDS 

.D T73FEDAO.VSAMDS 



ET.DFD74280.T861DAE1 .T73FEDA0. . . 
ET.DFD74280.T861DAE1 .T73FEDA0. . . 



4^0 



* MISCOMPARES - HIGH USED RBA 



LISTCRA DUMP COMPARE Output Notes: 

1. The 3-byte CRA control interval number in hexadecimal form. 

2. Each pair of hexadecimal-data lines are the information in the catalog 
recovery area's copy of the catalog record, followed by the information in 
the catalog record, for the same displacement. 

3. Asterisks are printed below the bytes in which a mi scompare exists and, in 
the left margin, the miscompared lines are flagged with a single asterisk. 

4. See "Regaining Access to Data" under "Catalog Recovery" in the chapter on 
Data Security and Protection for the cause and seriousness of this 
MISCOMPARES message. 

Figure 28. An Example of LISTCRA DUMP COMPARE Output 



454 0S/VS2 Access Method Services 



APPENDIX E. SAMPLE OUTPUT FROM CHKLIST 



Figure 29 shows the format of output from the CHKLIST command. 

For each checkpoint entry listed under "CHECKID>" the other 
columns give dsname, ddname, unit, and volume information for 
each tape data set that was open at the time of the checkpoint. 
Asterisks under "UNIT" indicate an unrecognizable unit type. 
"VOLUME X OF Y IS CURRENT" indicates the volume sequence number 
of the volume mounted at the time of the checkpoint and the 
total number of volumes in the data set. Each volume's volume 
serial number is listed, and an asterisk indicates the volume 
mounted at the time of the checkpoint. 



CHKLIST INFILE(CHKPT) CHECKID(C0000001 C0000002) 

IDCAMS SYSTEM SERVICES TIME: 21:34:43 01/16/75 

OPEN TAPE DATA SET LIST FROM CHECKPOINT DATA SET - CHKPT DATASET 



CHECKID 
C0000001 



DSNAME 

USER . TAPE . DATASETO 
USER . TAPE . DATASET 1 
USER . TAPE . DATASET2 



DDNAME UNIT 

DDN2VS11 2400-7TRK 

DDN3VS11 2400-9TRK 

DDN4VS11 3400-7TRK 



USER. TAPE. DATASET3 DDNAME32 2400-9TRK 



USER. TAPE. DATASET4 DDNAME42 2400-9TRK 



IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 29. An Example of CHKLIST Output 



VOLUMES 


- * INDICATES CURRENT VOLUME 


VOLUME 


1 OF 


1 IS CURRENT 




120001* 








VOLUME 


3 OF 


4 IS CURRENT 




130001 


130002 


130003* 130004 




VOLUME 


1 OF 


1 IS CURRENT 




140001* 








VOLUME 


8 OF 


8 IS CURRENT 




230001 


230002 


230003 230004 


230005 


230006 


230007 


230008* 




VOLUME 


20 OF 


24 IS CURRENT 




240001 


240002 


240003 240004 


240005 


240006 


240007 


240008 240009 


240010 


240011 


240012 


240013 240014 


240015 


240016 


240017 


240018 240019 


240020* 


240021 


240022 


240023 240024 
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APPENDIX F. COMMAND REFERENCE SUMMARY 



This section shows the format of each Access Method Services 
functional command, parameter abbreviation, and defaults. The 
commands are grouped together to allow you to remove these pages 
and use them for a qui ck, reference. 



456 0S/VS2 Access Method Services 



ALTER — MODIFY ATTRIBUTES OF A DATA SET CATALOGED IN A VSAM CATALOG 



Parameters 


Abbrev. 


ALTER 


— 


entrynameC/ password] 


— 


[ADDVOLUKES(volser[b volser...])] 


AVOL 


[ATTEMPTS (number)] 


ATT 


[AUTHORIZATION(entrypoint[b string] )] 


AUTH 


[BUFFERSPACE(size)] 


BUFSP, BUFSPC 


[CODE(code)] 


— 


[CONTROLPMC password)] 


CTLPW 


[DESTAGEWAIT|NODESTAGEWAITJ 


DSTGW NDSTGW 


[ EMPTY INOEMPTY] 


EMP NEMP 


CERASElNOERASE] 


ERAS NERAS 


CEXCEPTIONEXIT(entrypoint)] 


EEXT 


CFILE(dname)] 


— 


CFREESPACE(CI-percent[b CA-percent3 )] 


FSPC 


[INHIBIT IUNINHIBIT] 


INH UNINH 


[KEYSQength b offset)] 


— 


[MASTERPU(password)] 


MRPW 


[NEWNAME(newname)] 


NEWNM 


[NULLIFYC 


NULL 


[ AUTH0RI2ATI0N(M0DULE I STRING) ] 


AUTH MDLE 




STRG 


[CODE] 


— 


[CONTROLPW] 


CTLPW 


[EXCEPTIONEXIT] 


EEXT 


[MASTERPM] 


MRPW 


[OWNER] 


— 


[READPW] 


RDPW 


[RETENTION] 


RETN 


[UPDATEPW])] 


UPDPW 


[ OWNER ( owner id)] 


— 


[READPWt password)] 


RDPW 


[RECORDSIZE(average b maximum)] 


RECSZ 


[REMOVEVOLUMES(volser[b volser. . . ] )] 


RVOL 


[SCRATCH INOSCRATCH] 


SCR NSCR 


-w[SHAREOPTIONS(crossregi on[b crosssystem] )] 


SHR 


[STAGE | BIND | CYLINDERFAULT ] 


CYLF 


[TO(date)|FOR(days)] 


— — 


[UNIQUEKEY 1 NONUNIQUEKEY] 


UNQK NUNQK 


[UPDATE INOUPDATE] 


UPD NUPD 


[UPDATEPW(password)] 


UPDPW 


[UPGRADE INOUPGRADE] 


UPG NUPG 


[WRITECHECK I NOWRITECHECK3 


WCK NWCK 


[CATALOG(catname[/password] )] 


CAT 
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BLDINDEX — BUILD ALTERNATE INDEXES FOR EXISTING VSAH CLUSTERS 



Parameters 


Abbrev. 


BLDINDEX 
{INFILEtdnameC/password] ) | 
INDATASETt en try name [/password] )} 
{OUTFILEC dname [/password] 

[b dnameC/password] . . . ] ) | 
OUTDATASET(entryname[ /password] 

Cb entryname[/password] . . . ] )} 
[CATALOGlcatnameC/password] )] 
[ EXTERNALSORT 1 INTERNALSORT ] 
[WORKFILESCdname b dname)] 


BIX 
IFILE 
IDS 
OFILE 

ODS 

CAT 

ESORT ISORT 

WFILE 



CHKLIST — IDENTIFY TAPE VOLUMES MOUNTED HHEN A CHECKPOINT MAS TAKEN 



Parameters 


Abbrev. 


CHKLIST 
INFILE(dname) 
[CHECKIDtcheckid... )] 
COUTFILECdname)] 


CKLST 
IFILE 
CHKID 
OFILE 



CNVTCAT — CONVERT OS CATALOG ENTRIES INTO 0S/VS2 VSAM CATALOG ENTRIES 



Parameters 


Abbrev. 


CNVTCAT 
{INFILE(dname)|INDATASET(entryname)} 
[CATALOG(catname[/password] )] 
[CVOLEQUATESUcatname bfvolser 

Cb volser...]) )[b( cat name. ..)...])] 
[LISTlNOLIST] 
[MASTERCATALOG(catname[/password])] 


"CNVTC 
IFILE IDS 
CAT 
CVEQU 

— NLIST 
MCAT 



DEFINE ALIAS — DEFINE AN ALTERNATE NAME FOR A USER CATALOG OR A NONVSAM DATA SET 



Parameters 


Abbrev. 


DEFINE 
ALIAS 
(NAME(aliasname) 
RELATE (en try name) ) 

[CATALOGtcatnameC/password] )] 


DEF 

REL 
CAT 
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DEFINE ALTERNATEINDEX — DEFINE A VSAH CATALOG ENTRY FOR AN ALTERNATE INDEX 



Parameters 


Abbrev. 


DEFINE ALTERNATEINDEX 


DEF AIX 


(NAME Gentry name) 


— 


RELATE(entryname[/password] ) 


REL 


(CYLINDERS 1 (pri ma ryCb secondary] ) 1 


CYL 


RECORDS 1 CprimaryCb secondary] ) I 


REC 


TRACKS 1 (primaryCb secondary])} 


TRK 


V0LUMES 2 (volser[b volser...]) 


VOL 


CATTEMPTS(number|2)] 


ATT 


CAUTHORIZATIONCentrypointCb string])] 


AUTH 


CBUFFERSPACE(size)] 


BUFSP, BUFSPC 


CCODE(code)] 


■ — 


CCONTROLINTERVALSIZE(size)] 


CISZ, CNVSZ 


[CONTRQLPUt password)] 


CTLPW 


CDESTAGEWAITlNODESTAGEMAIT] 


DSTGW NDSTGW 


[ERASE INOERASE] 


ERAS NERAS 


CEXCEPTIONEXIT(entrypoint)] 


EEXT 


CFILE(dname)] 


— 


[FREESPACE(CI-percentCb CA-percent] | 0)] 


FSPC 


CIMBEDINOIMBED] 


IMBD NIMBD 


[KEYRANGESUlowkey b highkey) 


KRNG 


[(lowkey b highkey)...])] 




CKEYSdength b offset|64 0)] 


— 


CMASTERPWCpassword)] 


MRPW 


C MODEL ( en trynameC/ pas sword] 


— 


Cb catnameE/password] ] )] 




[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNER(ownerid)] 


— 


[READPWC password)] 


RDPW 


[RECORDSIZECaverage b maximum! 


RECSZ 


4086 32600)] 




[REPLICATE INOREPLICATE] 


REPL NREPL 


[REUSElNOREUSE] 


RUS NRUS 


[SHAREOPTIQNSCcrossregi on 


SHR 


[b crosssystem] | 1 3)] 




[SPEEDlRECOVERY] 


— RCVY 


[STAGE! BIND ICYLINDERFAULT] 


CYLF 


[TO(date)|FOR(days)] 


— — 


[UNIQUE ISUBALLOCATION] 


UNQ SUBAL 


[UNIQUEKEY 1 NONUNIQUEKEY] 


UNQK NUNQK 


CUPDATEPW(password)] 


UPDPW 


[UPGRADE iNOUPGRADE] 


UPG NUPG 


[WRITECHECKINOWRITECHECK]) 


WCK NWCK 



(Conti nued) 
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DEFINE ALTERNATEINDEX (CONTINUED) 



Parameters 


Abbrev. 


[DATA 


— 


(EATTEMPTS(number)] 


ATT 


EAUTHORIZATION(entrypointEb string])] 


AUTH 


EBUFFERSPACE(size)] 


BUFSP, BUFSPC 


[CODE (code)] 


— 


ECONTROLINTERVALSIZE(size)] 


CISZ, CNVSZ 


ECONTROLPW(password)] 


CTLPW 


ECYLINDERS(primaryEb secondary])! 


CYL 


RECORDS(primaryCb secondary])! 


REC 


TRACKS(pri maryEb secondary])] 


TRK 


EDESTAGEUAIT I NODESTAGEWAIT ] 


DSTGW NDSTGW 


C ERASE INOERASE] 


ERAS NERAS 


C EXCEPTIONEXIT ( ent rypo i nt ) ] 


EEXT 


[FILE(dname)] 


— 


CFREESPA6E(CI-percentEb CA-percent] )] 


FSPC 


CKEYRANGES((lowkey b highkey) 


KRNG 


Edowkey b highkey)...!)] 




[KEYSdength b offset)] 


— 


EMASTERPU(password)] 


MRPW 


C MODEL ( en try name C /password] 


— 


[b catnameE/password] ] )] 




E NAME (en try name)] 


— 


EORDEREDI UNORDERED] 


ORD UNORD 


EOWNER(ownerid)] 


— 


EREADPM( password)] 


RDPW 


ERECQRDSIZE(average b maximum)] 


RECSZ 


EREUSElNOREUSE] 


RUS NRUS 


ESHAREOPTIONS(crossregionEb crosssystem] )] 


SHR 


ESPEEDIRECOVERY] 


— RCVY 


ESTAGE | BIND | CYLINDERFAULT ] 


CYLF 


E UNIQUE | SUBALLOCATION] 


UNQ SUBAL 


EUNIQUEKEY J NONUNIQUEKEY] 


UNQK NUNQK 


EUPDATEPW( password)] 


UPDPW 


EVQLUMESEvolserEb volser...])] 


VOL 


EWRITECHECKlNOWRITECHECK])] 


WCK NWCK 



(Conti nued) 
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DEFINE ALTERNATEINDEX (CONTINUED) 



Parameters 


Abbrev. 


[INDEX 


IX 


([ATTEMPTS (number) J 


ATT 


[AUTHQRIZATION(entrypoint[b string] )] 


AUTH 


[CODE(code)] 


— 


[CONTROLINTERVALSIZE(size)] 


CISZ, CNVSZ 


[CONTROLPU( password)] 


CTLPW 


[CYLINDERS(primary[b secondary] ) I 


CYL 


RECORDS(primary[b secondary])! 


REC 


TRACKS(primary[b secondary])] 


TRK 


[DESTAGEUAITlNODESTAGEWAIT] 


DSTGW NDSTGW 


[EXCEPTIONEXIT(entrypoint)] 


EEXT 


[FILE(dname)] 


— 


[ IMBED INOIMBED) 


IMBD NIMBD 


[MASTERPW(password)] 


MRPW 


[ MODEL ( en tryname[ /password] 


— 


[b catname[/password] ] ) ] 




[NAME (en try name)] 


— 


[ORDERED {UNORDERED] 


ORD UNORD 


[OWNER(ownerid)] 


— 


[READPW( password)] 


RDPW 


[REPLICATE INOREPLICATE] 


REPL NREPL 


[REUSEINOREUSE] 


RUS NRUS 


[SHAREOPTIONS(crossregion[b crosssystem] )] 


SHR 


[STAGE | BIND | CYLINDERFAULT ] 


CYLF 


[UNIQUE ISUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password)] 


UPDPW 


[VOLUMES(volser[b volser...])] 


VOL 


[ WRITECHECK I NOWRITECHECKJ ) ] 


WCK NWCK 


[CATALOG(catname[/password] )] 


CAT 



CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of ALTERNATEINDEX, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

2 V0LUMES must be specified as a parameter of ALTERNATEINDEX or 
as a parameter of both DATA and INDEX if MODEL is not specified, 
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DEFINE CLUSTER—DEFINE A VSAM CATALOG ENTRY FOR A VSAM CLUSTER 



Parameters 


Abbrev. 


DEFINE CLUSTER 


DEF CL 


(NAME (en try name) 


— 


(CYLINDERS 1 (primaryEb secondary]) I 


CYL 


RECORDS 1 (primaryEb secondary])! 


REC 


TRACKS 1 (primaryEb secondary])} 


TRK 


V0LUMES 2 (volserEb volser...]) 


VOL 


CATTEMPTS(number|2)] 


ATT 


CAUTHORIZATION(entrypointCb string])] 


AUTH 


EBUFFERSPACE(size)] 


BUFSP, BUFSPC 


ECODECcode)] 


— 


ECONTROLINTERVALSIZE( si ze) ] 


CISZ, CNVSZ 


CCONTROLPMC password)] 


CTLPW 


EDESTAGEWAIT INODESTAGEWAIT] 


DSTGW NDSTGW 


CERASEIN0ERASE3 


ERAS NERAS 


E EXCEPTIONEXIT ( entrypo i nt ) ] 


EEXT 


CFILE(dname)] 


— 


CFREESPACE 3 (CI-percent 


FSPC 


Eb CA-percent3|0 0)] 




C IMBED INOIMBED3 3 


IMBD NIMBD 


E INDEXED 1 NONINDEXED 1 NUMBERED] 


IXD NIXD NUMD 


EKEYRANGES 3 ((lowkey b highkey) 


KRNG 


Etlowkey b highkey)...])] 




EKEYS 3 (length b offset | 64 0)3 


— 


EMASTERPWt password)] 


MRPW 


EMODELC en trynameE/pas sword] 


. — 


Eb catnameE/password] 3 )] 




EORDEREDi UNORDERED] 


ORD UNORD 


EOWNER(owneri d)3 


— 


EREADPW(password)] 


RDPW 


ERECORDSIZE A (average b maximum)] 


RECSZ 


EREPLICATEINOREPLICATE3 3 


REPL NREPL 


EREUSEINOREUSE] 


RUS NRUS 


ESHAREOPTIONSEcrossregion 


SHR 


Eb crosssystem] | 1 3)1 




ESPANNED 1 NONSPANNED] 


SPND NSPND 


ESPEEDIREC0VERY3 


— RCVY 


ESTAGE 1 BIND | CYLINDERFAULT ] 


CYLF 


ETO(date)|FOR(days)3 




EUNIQUEISUBALLOCATION3 


UNQ SUBAL 


EUPDATEPWCpassword)] 


UPDPW 


EURITECHECKINOURITECHECK3) 


WCK NWCK 


EDATA 


__ 


(EATTEMPTS(number)3 


ATT 


EAUTHORIZATIONtentrypointEb string3)3 


AUTH 


EBUFFERSPACE(size)] 


BUFSP, BUFSPC 


ECODE(code)] 


- — 


ECONTROLINTERVALSIZE(size)3 


CISZ, CNVSZ 


ECONTROLPWE password) 3 


CTLPW 


ECYLINDERSEprimaryEb secondary3)| 


CYL 


RECORDSCprimaryEb secondary3)j 


REC 


TRACKSEprimaryEb secondary3)3 


TRK 


EDESTAGEWAIT I NODESTAGEWAIT 3 


DSTGW NDSTGW 


EERASEIN0ERASE3 


ERAS NERAS 


E EXCEPTIONEXITC entrypo int) 3 


EEXT 


EFILE(dname) 3 




EFREESPACE 3 (CI-percentEb CA-percent3 )3 


FSPC 


EKEYRANGES 3 ((lowkey b highkey) 


KRNG 


Etlowkey b hi ghkey ) . . . 3 ) 3 




EKEYSHlength b offset)] 


— 


EMASTERPW(password)] 


MRPW 



(Conti nued) 
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DEFINE CLUSTER (CONTINUED) 



Parameters 


Abbrev. 


[MODEL (en try name [/password 3 


— 


[b catname[/password) ] )] 




[NAME (en try name) ] 


— 


[ORDERED | UNORDERED] 


ORD UNORD 


[OWNER(ownerid)] 


— 


[READPW( password)] 


RDPW 


[RECORDSIZE(average b maximum)] 


RECSZ 


[REUSE INOREUSE] 


RUS NRUS 


[SHAREOPTIONS(crossregion[b crosssystem] )] 


SHR 


[SPANNED | NONSPANNED] 


SPND NSPND 


[SPEEDJRECOVERY3 


— RCVY 


[STAGE | BIND | CYLINDERFAULT] 


CYLF 


[UNIQUE ISUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW(password)] 


UPDPW 


[VOLUMES(volser[b volser...])] 


VOL 


[ WRITECHECK I NQWRITECHECK] ) ] 


WCK NWCK 


[INDEX 3 


IX 


UATTEMPTS(number)] 


ATT 


[AUTHORIZATION(entrypoint[b string])] 


AUTH 


[CODE(code)3 


— 


[CONTROLINTERVALSIZE(size)] 


CISZ,CNVSZ 


[CONTROLPW( password)] 


CTLPW 


[CYLINDERS(primary[b secondary] ) | 


CYL 


RECORDS(primary[b secondary])! 


REC 


TRACKS(primary[b secondary])] 


TRK 


[DESTAGEWAITlNODESTAGEWAIT] 


DSTGW NDSTGW 


[EXCEPTIONEXIT(entrypoint)] 


EEXT 


[FILE(dname)] 


— 


[IMBED|N0IMBED] 3 


IMBD NIMBD 


[MASTERPW(password)] 


MRPW 


[ MODEL ( en try name [ /password] 


— 


[b catname[/password] ] )] 




[NAME (en try name) ] 


— 


[ORDERED | UNORDERED] 


ORD UNORD 


[OWNER(ownerid)] 


— 


[READPW(password)] 


RDPW 


[REPLICATE | NOREPLICATE] 3 


REPL NREPL 


[REUSElNOREUSE] 


RUS NRUS 


[SHAREOPTIONS(crossregi on[b crosssystem] )] 


SHR 


[STAGE | BIND | CYLINDERFAULT ] 


CYLF 


[UNIQUE | SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password) ] 


UPDPW 


[VOLUMES(volser[b volser...])] 


VOL 


[WRITECHECKlNOWRITECHECK])] 


WCK NWCK 


[CATALOG(catname[/password] )] 


CAT 



CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of CLUSTER, as a parameter of DATA, or as a parameter 
of both DATA and INDEX if MODEL 

2 V0LUMES must be specified as a parameter of CLUSTER or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

3 Can only be specified for a key-sequenced cluster. 

4 When SPANNED is specified, the default is RECORDSIZE ( 4086 
32600 ). Otherwise, the default is RECORDSIZE (4089 4089). 
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DEFINE GENERATIONDATAGROUP — CREATE A CATALOG ENTRY FOR A GENERATION DATA GROUP 



Parameters 


Abbrev. 


DEFINE GENERATIONDATAGROUP 


DEF GDG 


(NAME (en try name) 


— 


LIMIT(limit) 


LIM 


[ EMPTY INOEMPTY] 


EMP NEMP 


[OWNER(ownerid)3 


— 


[ SCRATCH INOSCRATCH3 


SCR NSCR 


[TO(date)|FQR(days)3) 


— 


[CATAL0G(catname[/password3 )3 


CAT 



DEFINE NONVSAM — DEFINE A VSAM CATALOG ENTRY FOR A NONVSAM DATA SET 



Parameters 


Abbrev. 


DEFINE NONVSAM 


DEF NVSAM 


(NAME (en try name) 


— - 


DEVICETYPES(devtypeCb devtype. . . 3 ) 


DEVT 


VOLUMESUolserCb volser...3) 


VOL 


C FI LESEQUENCENUMBERS ( number 


FSEQN 


[b number* ..3)3 




[OKNER(ownerid)3 


— 


CTO(date)|FOR(days)3) 


— — 


CCATALOG(catnameC/password3 )3 


CAT 



DEFINE PAGESPACE — DEFINE A VSAM CATALOG ENTRY FOR A PAGE SPACE 



Parameters 


Abbrev. 


DEFINE PAGESPACE 


DEF PGSPC 


(NAME (en try name) 


— - 


{CYLINDERS(primary)! 


CYL 


RECORDS (primary) I 


REC 


TRACKS(primary)} 


TRK 


VOLUriE(volser) 


VOL 


tATTEMPTS(number|2)3 


ATT 


CAUTHORIZATION(entrypoint[b string3)3 


AUTH 


CCODE(code)3 


— 


[CONTROLPW( password) 3 


CTLPW 


[FILE(dname)3 


— - 


CMASTERPW( password) 3 


MRPW 


[MODEL (en try name [/pas sword 3 


— 


[b catname[/password33 )3 




[OWNER(ownerid)3 


- — 


[ R EADPW ( pa sswo rd ) 3 


RDPW 


[SMAPINOSWAP3 


— NSWAP 


[TO(date)|FOR(days)3 


— — 


[UNIQUE 1 SUBALLOCATION3 


UNQ SUBAL 


[UPDATEPW(password)3 ) 


UPDPW 


[CATALOG(catname[/password3 )3 


CAT 
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DEFINE PATH—DEFINE 
CLUSTER 



A RELATIONSHIP BETWEEN AN ALTERNATE INDEX AND ITS BASE 



Paramgters 


Abbrev. 


DEFINE PATH 


DEF — 


(NAME (en try name) 


— 


PATHENTRY(entrynameC/password] ) 


PENT 


CATTEMPTS(number|2)] 


ATT 


CAUTH0RI2ATI0N(entrypointCb string])] 


AUTH 


CCODE(code)] 


— 


[CONTROLPW( password)] 


CTLPW 


CFILE(dname)] 


— 


CMASTERPW(password)] 


MRPW 


C MODEL ( en trynameC /password] 


— 


Cb catnameC/password] ] ) ] 




EOWNER(ownerid)] 


— 


[READPW(password)] 


RDPW 


ETO(date)|FOR(days)] 


— — 


[UPDATE INOUPDATE] 


UPD NUPD 


CUPDATEPW(password)] ) 


UPDPW 


CCATALOG(catnameC/password] )] 


CAT 



DEFINE SPACE — DEFINE A VSAM DATA SPACE 



Parameters 


Abbrev. 


DEFINE SPACE 


DEF SPC 


( (CANDIDATE | 


CAN 


CYLINDERS(primaryCb secondary])! 


CYL 


RECORDS(primaryCb secondary]) 


REC 


b RECORDSIZE(average b maximum) | 


RECSZ 


TRACKS(primaryCb secondary])} 


TRK 


VOLUMES(volserCb volser...]) 


VOL 


CFILE(dname)]) 


— — 


CCATALOG(catnameC/password] )] 


CAT 



Appendix F. Command Reference Summary 465 



DEFINE USERCATALOG— CREATE A VSAM USER CATALOG 



Parameters 


Abbrev. 


DEFINE USERCATALOG I MASTERCATALQG 


DEF UCAT MCAT 


(NAME (en try name) 


— . 


{CYLINDERS (primary Eb secondary] ) I 


CYL 


RECORDS(primaryCb secondary])! 


REC 


TRACKS(primaryCb secondary])} 


TRK 


VOLUME(volser) 


VOL 


CATTE«PTS(number|2)] 


ATT 


CAUTHORIZATION(entrypointCb string])] 


AUTH 


CBUFFERSPACE( si ze 1 3072) ] 


BUFSP, BUFSPC 


CCODE(code)] 


— 


CCONTROLPW( password)] 


CTLPW 


[DESTAGEWAIT INODESTAGEMAIT] 


DSTGW NDSTGW 


CFILE(dname)] 


— 


CMASTERPW(password)] 


MRPW 


E MODEL (entrynameC /password] 


— 


Cb catnameC/password] ] )] 




[Ok'NER(ownerid)] 


— 


[READPU(password)] 


RDPW 


[RECOVERABLE! NOTRECOVERABLE] 


RVBL NRVBL 


CTO(date)|FOR(days)] 


— — 


CUPDATEPW(password)] 


UPDPW 


[WRITECHECK INOWRITECHECK]) 


WCK NWCK 


CDATA 


— 


UBUFFERSPACE(siee)] 


BUFSP, BUFSPC 


[CYLINDERS(primaryCb secondary] ) | 


CYL 


RECORDS(primary[b secondary])! 


REC 


TRACKS(primary[b secondary])] 


TRK 


EDESTAGEMAIT INODESTAGEMAIT] 


DSTGW NDSTGW 


[RECOVERABLE | NOTRECOVERABLE] 


RVBL NRVBL 


[ WRITECHECK | NOWRITECHECK] ) 3 


WCK NWCK 


[INDEX 


IX 


([CYLINDERS(primary)! 


CYL 


RECORDS(primary ) I 


REC 


TRACKS(primary)] 


TRK 


[ DESTAGEWAIT | NODESTAGEWAIT ] 


DSTGW NDSTGW 


[WRITECHECK | NOWRITECHECK] )] 


WCK NWCK 


[CATALOG(mastercatname[/password] ) ] 


CAT 
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DELETE — DELETE ENTRIES FROM A VSAM CATALOG 



Parameters 


Abbrev. 


DELETE 


DEL 


(en try name E/pa s sword] 


— 


Cb entrynameC/password] . . . 3 ) 




CALIASl 


— 


ALTERNATEINDEXl 


AIX 


CLUSTER | 


CL 


GENERATIONDATAGROUP I 


GDG 


NONVSAMl 


NVSAM 


PAGESPACEl 


PGSPC 


PATHl 


— 


SPACE 1 ! 


SPC 


USERCATALOG 1 ! 


UCAT 


[ ERASE INOERASE] 


ERAS NERAS 


CFILE(dname)] 


— 


C FORCE INOFORCE] 


FRC NFRC 


[ PURGE IKOPURGE] 


PRG NPRG 


[SCRATCH INOSCRATCH] 


SCR NSCR 


CCATALOG(catname[/password3 )] 


CAT 



1 When you delete a data space or catalog, you cannot delete any 
other type of entry. You must identify the type of entry to be 
deleted, by specifying SPACE or USERCATALOG. 



EXPORT — DISCONNECT A VSAM USER CATALOG 



Parameters 


Abbrev. 


EXPORT 

user cat name [/password 3 
DISCONNECT 


EXP 
DCON 



EXPORT — COPY A VSAM CLUSTER OR ALTERNATE INDEX, TOGETHER WITH ITS CATALOG 
ENTRIES, TO A SEQUENTIAL DATA SET 



Parameters 


Abbrev. 


EXPORT 


EXP 


entryname[/password3 


— 


COUTFILE( dname ) 1 OUTDATASET ( ent ryname ) } 


OFILE ODS 


[INFILE(dname)3 


IFILE 


[ERASE INOERASE] 


ERAS NERAS 


[ INHIBITSOURCE 1 NOINHIBITSOURCE3 


INHS NINHS 


[INHIBITTARGETINOINHIBITTARGET3 


INHT NINHT 


[PURGE INOPURGE3 


PRG NPRG 


[TEMPORARY I PERMANENT 3 


TEMP PERM 
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EXPORTRA—COPY CATALOG ENTRIES FROM THE CATALOG RECOVERY AREA (CRA) 



Parameters 


Abbrev. 


EXPORTRA 


XPRA 


OUTFILE(dname) 


OFILE 


CRA( 


— 


(dnamel 




(ALLCb INFILE(dname2)]| 


— IFILE 


ENTRIESC 


ENT 


(entrynameCb dname33) 




C (entrynameEb dname33 ). . . 3 ) I 




NONE) ) 


— 


[(dnamel. ..)... 3 ) 




C FORCE 1NOFORCE3 


FRC NFRC 


[MASTERPUC password) 3 


MRPW 



IMPORT — CONNECT A VSAM USER CATALOG 



Parameters 


Abbrev. 


IMPORT 
CONNECT 
OBJECTSt (usercatname 

DEVICETYPE(devtype) 

VOLUMES(volser))) 

[CATALOG(mastercatnameC/password3 ) 3 


IMP 

CON 

OBJ 

DEVT 

VOL 

CAT 



IMPORT — RESTORE A VSAM CLUSTER OR ALTERNATE INDEX FROM A PORTABLE DATA SET 
CREATED BY THE EXPORT COMMAND 



Parameters 


Abbrev. 


IMPORT 


IMP 


(INFILE(dname)|INDATASET(entryname)} 


IFILE IDS 


{QUTFILE(dnameC/password3 ) I 


OFILE 


OUTDATASETC en tryname[ /password 3 )} 


ODS 


[ ERASE INOERASE3 


ERAS NERAS 


[INTOEMPTY3 


IEMPTY 


[OBJECTS ( (entryname 


OBJ 


[FILE(dname)3 


— 


[KEYRANGESCUowkey b highkey) 


KRNG 


[(lowkey b hi ghkey ) . . . 3 ) 3 




[NEUNAME(newname)3 


NEWNM 


[ORDERED | UNORDERED 3 


ORD UNORD 


[VOLUMES(volser[b volser. . . 3 )3 ) 


VOL 


[ C en try name. ..)... 3 )3 




[PURGEINOPURGE3 


PRG NPRG 


[SAVRACINOSAVRAC3 


— — 


[CATALOG(catname[/password3 )3 


CAT 
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IMPORTRA— RESTORE CATALOG ENTRIES FROM A PORTABLE DATA SET CREATED BY THE 
EXPORTRA COMMAND 



Parameters 


Abbrev. 


IMPORTRA 
UNFILE( dname) I INDATASET( entryname)} 
[OUTFILE(dname)3 
[QBJECTS( 


MPRA 

IFILE IDS 
OFILE 
OBJ 


(entryname 

[DEVICETYPES(devtypeCb devtype. ..3)3 

CFILE(dname)3 

CVOLUMES(volserCb volser. . . 3 )3 ) 
C (entryname. ..)... 3 )3 
CSAVRAClNOSAVRAC] 


DEVT 
VOL 


[CATALOG(catname[/password3 )3 


CAT 



LISTCAT — LIST ENTRIES FROM A CATALOG 



Parameters 


Abbrev. 


LISTCAT 


LISTC 


[CATALOG(catname[/password3 )3 


CAT 


[ENTRIES(entryname[ /password 3 


ENT 


[b entrynameC/password3 . . . 3 ) | 




LEVELC level )3 


LVL 


[ALIAS] 


— 


Cb ALTERNATEINDEX3 


AIX 


Cb CLUSTER] 


CL 


Cb DATA3 


— 


Cb GENERATIONDATAGROUP3 


GDG 


Cb INDEX] 


IX 


Cb NONVSAM] 


NVSAM 


Cb PAGESPACE3 


PGSPC 


Cb PATH3 


— 


Cb SPACE3 

Cb USERCATALOG3 


SPC 


UCAT 


CALL! 


— 


ALLOCATION | 


ALLOC 


HISTORY | 


HIST 


NAMEl 


— 


VOLUME] 


VOL 


[CREATION! days) 3 


CREAT 


CEXPIRATION(days)] 


EXPIR 


CNOTUSABLE3 


NUS 


COUTFILE(dname)3 


OFILE 



LISTCRA — LIST THE CONTENTS OF THE CATALOG RECOVERY AREA (CRA) 



Parameters 


Abbrev. 


LISTCRA 
INFILEtdnameCb dname...]) 
[CATALOG (cat name [/password 3b dname)] 
[COMPARE INOCOMPARE] 
[DUMP ! NAME | SEQUENTIALDUMP3 
[MASTERPW( password)] 
[OUTFILE(dname)] 


LISTR 

IFILE 

CAT 

CMPR NCMPR 

SDUMP 

MRPW 
OFILE 
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PRINT — PRINT THE CONTENTS OF A DATA SET 



Parameters 



Abbrev. 



PRINT 
{INFILEtdnameC/password3 ) I 

INDAT AS ET ( en try name C /password 3 )} 
COUTFILE(dname)] 
C CHAR ACT ER | DUMP | HEX 3 
C FROMKEY ( keyTTFROM ADDRESS (address ) 

FROMNUMBER( number )| SKIP t count) 3 
CTOKEY(key ) |TOADDRESS(address) I 

TONUMBERC number)! COUNT (count) 3 



IFILE 

IDS 

OFILE 

CHAR 

FKEY FADDR 
FNUM — 
— TADDR 
TNUM — 



REPRO — COPY DATA SETS 



Parameters 


Abbrev. 


REPRO 


— 


(INFILE(dname[ /password 3 


IFILE 


Cb ENVIRONMENT(DUMMY)3)| 


ENV DUM 


INDATASETt en trynameC /pa ssword3 


IDS 


Cb ENVIRONMENT C DUMMY) 3)} 


ENV DUM 


{OUTFILE(dnameC/password3 ) I 


OFILE 


OUTDATASETCentrynameC/password3 )} 


ODS 


[REPLACE INOREPLACE3 


REP NREP 


[REUSEINOREUSE3 


RUS NRUS 


[ FROMKEY ( key ) I FROMADDRESS ( address ) | 


FKEY FADDR 


FROMNUMBER( number )|SKIP( count) 3 


FNUM — 


CTOKEY(key ) iTOADDRESS(address) | 


— TADDR 


TONUMBER( number ) I COUNT ( count ) 3 


TNUM — 



RESETCAT — SYNCHRONIZE A RECOVERABLE CATALOG TO THE LEVEL OF ITS QKNED VOLUMES 



Parameters 


Abbrev. 


RESETCAT 
CATALOG(catnameC/password3 Cb dname3 ) 
{CRAFILESKdnamelCb ALL|b NONE3) 
UdnamelCb ALL|b NONE]).. .3)1 
CRAVOLUMES((volserCb devtype3 ) 
CCvolserCb devtype] ) . . . 3 )> 
CIGNOREINOIGNORE3 
CMASTERPW(password)3 
CWORKCAT(catnameC/password3 )3 
CWORKFILE(dnameC/password3 )3 


RCAT 
CAT 

CRAVOL 

IGN NIGN 
MRPW 
WCAT 
WFILE 



VERIFY — RESTORE A VSAM CLUSTERS ENP-OF-FILE VALUES 



Parameters 


Abbrev. 


VERIFY 
{FILE(dnameC/password3 ) I 
DATASET ( en try name C /password 3 )) 


VFY 
DS 



470 0S/VS2 Access Method Services 



EXECUTION CONTROL COMMANDS 



IF-THEN-ELSE COMMAND SEQUENCE 



PARM COMMAND 



SET COMMAND 



Parameters 


Abbrev. 


IF 
(LASTCClMAXCC) Lb] comparand!! b]number 
THENCb commandl 

DO 

command set 

END] 
CELSECb commandl 

DO 

command set 

END3] 





Parameters 


Abbrev. 


PARM 
CTEST( 
{[TRACE] 

C AREAS ( area idCb area id...])] 
CFULL(tdumpidCb countlEb count2]]) 

C (dumpi d. ..)...])] | 
OFF})] 
[GRAPHICS (CHAIN( cha i n ) I TABLECmname ) ) ] 
[MARGINStleftmargi n b ri ghtmargi n )] 





Parameters 


Abbrev. 


SET • 
(MAXCC I LASTCC) [b] = [b]n.umber 
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APPENDIX G. INVOKING ACCESS METHOD SERVICES FROM A PROBLEM PROGRAM 



Access Method Services can be invoked by a problem program 
through the use of the ATTACH, LINK, or LOAD and CALL macro 
i nstructi ons. 

The dynamic invocation of Access Method Services enables 
respeci f icati on of selected processor defaults as well as the 
ability to manage input/output operations for selected data 
sets. 



AUTHORIZED PROGRAM FACILITY (APF) 



There are six Access Method Services commands which require APF 
authorization; they are: 

REPRO — when using the copy-catalog or catalog unload/reload 
facility. 

PRINT — when the object to be printed is a VSAM catalog. 

LISTCRA 

EXPORTRA 

RESETCAT 

VERIFY — when a VSAM catalog is to be verified. 

If the problem program invoking Access Method Services needs to 
perform any of these functions, it must be authorized and be 
located in an authorized library. Additionally, a User I/O 
Routine must reside in an authorized library if the problem 
program it is associated with is authorized. See "Authorized 
Program Facility (APF)" in 0S/VS2 System Programming Library* 
Supervi sor , for information about program authorization. 



INVOKING MACRO INSTRUCTIONS 



The following descriptions of the invoking macro instructions 
are related to Figure 30, which describes the argument lists 
referenced by the invoking macros. 



LINK OR ATTACH MACRO INSTRUCTION 



Access Method Services may be invoked through either the LINK or 
the ATTACH macro instruction. 

The format of the LINK or ATTACH macro instruction is* 

[name] 

{LINK | ATTACH} 
EP=IDCAMS, 
PARAM=Copti onaddr 
C >dnameaddr] 
C #pgnoaddr3 
[ , i oli staddr] )> 
VL = 1 

EP=IDCAMS 

specifies that the program to be invoked is IDCAMS. 
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PARAM= 

specifies the addresses of the parameters to be passed to 
IDCAMS. These values can be coded: 



opti onaddr 

specifies the address of an option list, which can be 
specified in the PARM parameter of the EXEC statement 
and is a valid set of parameters for the Access Method 
Services PARM command. If you do not wish to specify 
any options, this address must point to a halfword of 
binary zeros. Figure 30 shows the format of the 
opti ons li st . 

dnameaddr 

specifies the address of a list of alternate DD names 
for standard data sets used during IDCAMS processing. 
If standard DD names are used and this is not the last 
parameter in the list, it should point to a halfword 
of binary zeros. If it is the last parameter, it may 
be omitted. Figure 30 shows the format of the 
alternate DD name list. 

pgnoaddr 

specifies the address of a 6-byte area which contains 
ar\ EBCDIC starting page number for the system output 
file. If the page number is not specified, but this is 
not the last parameter in the list, the parameter must 
point to a halfword of binary zeros. If it is the last 
parameter, it may be omitted. If omitted the default 
page number is 1. Figure 30 shows the format of the 
page-number area. 

iolistaddr 

specifies the address of a list of 

externally-controlled data sets and the addresses of 
corresponding I/O routines. If no external I/O 
routines arQ supplied, this parameter may be omitted. 
Figure 30 shows the format of the I/O list. 



VL=1 



causes the high-order bit of the last address 
parameter of the PARAM list to be set to 1. 



LOAD AND CALL MACRO INSTRUCTIONS 



Access Method Services may also be invoked via a LOAD of the 
module IDCAMS, followed by a CALL to that module. The format of 
the LOAD macro instruction is* 



[name] 


LOAD 


{EP=IDCAMS|EPLOC=address of name} 



where: 

EP=IDCAMS 

is the entry point name of the IDCAMS program to be loaded 
into virtual storage. 

EPLQC=address of name 

is the address of an 8-byte character string 'IDCAMS bb' . 
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After loading IDCAMS* Register 15 must be loaded with the 
address returned from the LOAD macro. Then CALL may be used to 
pass control to IDCAMS. The format of the CALL macro instruction 

is: 





LR 


15,0 


[name] 


CALL 


(15), 

(opt i onaddr 
C » dnameaddr] 
C , pgnoaddr] 
[ , i ol i staddr] ), 
VL 



where* 



15 



is the register containing the address of the entry point 
to be given control. 



opti onaddr 

specifies the address of an options list which can be 
specified in the PARM parameter of the EXEC statement and 
is a valid set of parameters for the Access Method Services 
PARM command. If you do not wish to specify any options* 
this address must point to a halfword of binary zeros. 
Figure 30 shows the format of the options list. 

dnameaddr 

specifies the address of a list of alternate "DD names for 
standard data sets used during IDCAMS processing. If 
standard DD names are used and this is not the last 
parameter in the list* it should point to a halfword of 
binary zeros. If it is the last parameter* it ntay be 
omitted. Figure 30 shows the format of the alternate DD 
name 1 i st . 



pgnoaddr 

specifies the address of a 6-byte area which contains an 
EBCDIC starting page number for the system output file. If 
the page number is not specified, but this is not the last 
parameter in the list* the parameter must point to a 
halfword of binary zeros. If it is the last parameter* it 
may be omitted. If omitted the default page number is 1. 
Figure 30 shows the format of the page number area. 

i oil staddr 

specifies the address of a list of externally controlled 
data sets and the addresses of corresponding I/O routines. 
If no external I/O routines are supplied* this parameter 
may be omitted. Figure 30 shows the format of the I/O list 



VL 



causes the high-order bit of the last address parameter in 
the macro expansion to be set to 1 . 



INVOCATION FROM A PL/I PROGRAM 



Access Method Services may also be invoked from a PL/I program 
using the facilities of the IBM PL/I Optimizing Compiler Program 
Product. IDCAMS must be declared to the compiler as an external 
entry point with the ASSEMBLER and INTER options. The Access 
Method Services processor is loaded by issuing a FETCH IDCAMS 
statement* is branched to via a CALL statement* and deleted via 
a RELEASE IDCAMS statement. The format of the CALL statement is= 



CALL 


IDCAM 


(optionsE, dnames] C,pageno]C, ioli st] ); 



where : 
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opt i ons 

specifies a valid set of parameters for the Access Method 
Services PARM command. If no parameters are: to be 
specified/ options should be a halfword of binary zeros. 
Figure 30 shows the format of the options area. 

dnames 

specifies a list of alternate DD names for standard data 
sets used during IDCAMS processing. If standard DD names 
are used and this is not the last parameter in the list, 
dnames should be a halfword of binary zeros. If it is the 
last parameter, it may be omitted. Figure 30 shows the 
format of the alternate DD names list. 

pageno 

specifies a 6-byte field that contains an EBCDIC starting 
page number for the system output file. If the page number 
is not specified, but this is not the last parameter in the 
list, the parameter must be a halfword of binary zeros. If 
it is the last parameter, it may be omitted. If not 
specified, the default page number is 1. Figure 30 shows 
the format of the page number area. 

i oli st 

specifies a list of externally controlled data sets and the 
addresses of corresponding I/O routines. If no external I/O 
routines are supplied, this parameter may be omitted. 
Figure 30 shows the format of the I/O list. 



PROCESSOR INVOCATION 



Figure 30 shows the processor invocation argument list as it 
exists in the user's area. 

Entry and exit to the Access Method Services processor occur 
through IDCSA01, a module of the System Adapter. Standard 
linkage is used; that is, register 1 points to the argument 
list, register 13 points to a save area, register 14 contains 
the return address, and register 15 contains the entry point 
address for IDCSA01. On exit from the Access Method Services 
processor, register 15 contains the value of MAXCC (see the 
section "Processor Condition Codes" below). 



The argument list, as shown inFigure 30, can be a maximum of 
four fullword addresses pointing to strings of data. The last 
address in the list contains a "1" in the sign field. The first 
three possible strings of data each begin with a two-byte length 
field. A null element in the list can be indicated by either an 
address of zeros or a length of zero. 
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OPTIONS LIST 



LENGTH 




■*)- 



OPTIONS 
—il 



OPTIONS LIST: Required. Provides a 
way to specify processing options. If 
you do not wish to specify any options, 
you must set the LENGTH field to 
binary zeros. 

LENGTH: Halfword which specifies the 
number of bytes in the OPTIONS field. 

OPTIONS: Character string which con- 
tains the processing options of the. Access 
Method Services PARM command. The 
options may be specified in the PARM 
field of the EXEC statement or they may 
be set up by the problem program. The 
options must comply to the parameter 
syntax of the Access Method Services 
PARM command. 



PAGE NUMBER LIST: Optional. Provides 
a way to specify the starting page number 
for system output. 

LENGTH: The number of bytes in the 
PAGE NUMBER field. 



PAGE NUMBER: 1-4 byte character string which may 
specify the starting page number of system output listing. 
This value is reset to the current page number upon 
completion of the present invocation of the Access 
Method Services processor. 



INPUT /OUTPUT LIST 



DNAME i 



t 



IOROUTINE i 



| USER DATA j 



LENGTH 



00000000 



00000000 



00000000 



00000000 



SYSINbb 



SYSPRINT 



INPUT/OUTPUT LIST: Optional. Provides the means of 
identifying those data sets for which the invoker wishes to 
manage all I/O operations. 

n: A fullword which specifies the number of groups of 
three fields that follows. Each group consists of a DNAME 
address, an IOROUTINE address and a USER DATA address. 

DNAME: Address of a character string which identifies a 
data set which will result in the invocation of the associated 
IOROUTINE for all I/O operations (including OPEN and 
CLOSE) against the data set. The character string identifies 
the data set as either a 10-byte or 46-byte character string 
as follows: 

A 10-byte character string: the first two characters are 'DD\ 
the next 8 characters are the DNAME field value left-justified 
(padded with blanks if necessary) which may appear in the 
FILE, INFILE or OUTFILE parameters of any Access 
Methods Services command. The SYSIN and SYSPRINT 
ddnames may also appear if the invoker wishes to manage 
these data sets. 

A 46-byte character string: the first two characters are 
'DS' the next 44 characters are the data set name, left- 
justified (padded with blanks if necessary), which may appear 
in the INDATASET, OUTDATASET, or DATASET para- 
' meters of any Access Method Services command. 

IOROUTINE: Address of the program which is to be 
invoked to process I/O operations upon the data set asso- 
ciated with DNAME. This routine, instead of the processor, 
will be invoked for all operations against the data set. See 
the section "User I/O Routines" in this appendix for linkage 
and interface conventions between the IOROUTINE and 
Access Method Services. 

USER DATA: Address of a data area user may use for any purpose. 

Figure 30. Processor Invocation Argument List From a Problem Program 



DNAMEn 



t 



IOROUTINE,, 



| USER DAT A n 



DNAMESLIST: Op- 
tional. Provides a way to 
specify alternative names 
for the SYSIN and 
SYSPRINT data sets. 

LENGTH: Halfword which 
specifies the number of 
bytes in the remainder 
of the list. 

DNAMES: Unseparated 
eight-character DDnames, 
left justified and padded 
with blanks. To change 
the name of SYSIN or 
SYSPRINT supply an 
alternate name in the 
same position. If an 
alternate name is not 
supplied, the standard 
name is assumed. If the 
name is not supplied 
with the list, the eight- 
byte entry must contain 
binary zeros. Names in 
any position other than 
those for SYSIN and 
SYSPRINT are 
ignored. 
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PROCESSOR CONDITION CODES 



The processor's condition code is LASTCC, which can be 
interrogated in the command stream following each functional 
command. The possible values, their meanings, and examples of 
causes are in the following table. The table illustrates the 
value of LASTCC. 

Code Meaning 

The function was executed successfully. Informational 
messages may have been issued. 

4 Some annoyance in executing the complete function was met, 
but it was possible to continue. The results may not be 
exactly what the user wants, but no permanent harm appears 
to have been done by continuing. A warning message was 
i ssued. 

8 A function could not perform all that was asked of it. The 
function was completed, but specific details were 
bypassed. 

12 The entire function could not be performed. 

16 Severe error or problem encountered. Remainder of command 
stream is flushed and processor returns condition code 16 
to the operating system. 

LASTCC is set by the processor at the completion of each 
functional command. MAXCC, which can also be interrogated in the 
command stream, is the highest value of LASTCC thus far 
encountered. 



USER I/O ROUTINES 



User I/O routines enable a user to perform all I/O operations 
for a data set which would normally be handled by the Access 
Methods Services processor. This makes it possible, for 
instance, to control the command input stream by providing an 
I/O routine for SYSIN. 

A user I/O routine is invoked by Access Method Services for all 
operations against the selected data sets. The identification of 
the data sets and their associated I/O routines is via the 
input/output list of the processor invocation parameter list 
( see Fi gure 30 ) . 

When writing a user I/O routine, the user must be aware of three 
things 1 First, the processor handles the user data set as if it 
were a nonVSAM data set that contains variable-length unblocked 
records (maximum record length is 32,760 bytes) with a physical 
sequential organization. The processor does not test for the 
existence of the data set. Second, the user must know the data 
format so that the user's routine can be coded to handle the 
correct type of input and format the correct type of output. 
Third, each user routine must handle errors encountered for data 
sets it is managing and provide a return code to the processor 
in register 15. The processor uses the return code to determine 
what it is to do next. 

The permissible return codes are'> 

• — operation successful 

• 4 — end of data for a GET operation 

• 8 — error encountered during a GET/PUT operation, but 
continue processing 
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• 12 — do not allow any further calls (except CLOSE) to this 
routi ne 

Figure 31 shows the argument list used in communication between 
the user I/O routine and the Access Method Services processor. 
The User I/O routine is invoked by the processor for OPEN* 
CLOSE, GET, and PUT routines. 

The type of operation to be performed is indicated via IOFLAGS. 
The IOINFO field indicates, for OPEN and CLOSE operations, the 
data set name or ddname of the data set; for GET and PUT 
operations, the IOINFO field is used to communicate the record 
length and address. 

A user I/O routine for SYSPRINT receives control each time the 
processor issues a PUT against the SYSPRINT data set. If the PUT 
has been issued to print an IDC message, the unique message 
number is passed to the routine via IOFLAGS (see Figure 31). 
Each IDC message is in the form IDCsnnnI or IDCsnnnnI, where : 

s is a code indicating the severity of the problem 

nnn or nnnn is the message number which is unique across all 
IDC messages 

The 2-byte message number passed via IOFLAGS is the nnn or nnnn 
portion of the message converted to binary. 
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A USER DATA 
| IOFLAGS 
| IOINFO 




User data pointer obtained from the 
input/output list of the processor 
invocation parameter list. (See Figure 30.) 



OPEN 



DNAME or 
DATASETNAME 



DNAME: 8-byte field, left-justified 
(padded with blanks if necessary) 
containing the DDname. 

DATASETNAME: 44-byte field 
(padded with blanks if necessary) 
containing the data set name. 

CLOSE 



For a GET, this information 
is returned to the processor 
by the user's I/O routine in 
the 8-byte area passed to the 
routine. 




FLAGS 





Fullword of Flags: 


Value or 


Meanin 


DATASETNAME: 44-byte 




Bit Pattern 




field (padded with blanks 


Byte 1 


X'00' 


OPEN 


if necessary) containing 


(Operation) 


X'04' 


CLOSE 


the data set name. 




X'08' 


GET 






X'OC 


PUT 



Byte 2 



Bytes 3, 4 
(Record type 
for PUT only) 



1 . 



. 1 



For a PUT, the processor gives 
this information to the user's 
I/O routine. 

Record (GET): Address of 
retrieved record. 

Record Length (GET): Full- 
word length of retrieved 
record. 

Record (PUT): Address of 
record to be written. 

Record Length (PUT): Full- 
word length of record to be 
written. 



Figure 31. Arguments Passed to and From a User I/O Routine 



OPEN for input 
OPEN for output 
Indicates IOINFO 
contains the address 
of a DDname on OPEN. 

Indicates IOINFO contains 
the address of a data set 
name on OPEN. 

Normal data record is to 
be written. 



Message serial number 
converted to binary if 
IDC message is to be 
written. (See "User I/O 
Routine" for a description 
of this value.) 



Appendix G. Invoking Access Method Services from a Problem Program 479 



APPENDIX H. CHANGING THE ATTRIBUTES OF THE VSAM MASTER CATALOG 



At some point in time in an existing 0S/VS2 MVS system, you may 
wish to change some of the attributes of your VSAM master 
catalog. For example, you may wish to convert the VSAM master 
catalog from nonrecoverable to recoverable, or take advantage of 
a new VSAM enhancement. This is an example of the conversion 
process. A description of the process precedes an actual example 
of each step. When you understand the example's objectives, you 
can modify it so that it is appropriate for your system. 

1. Install on your system the level (or higher level) of VSAM 
and Access Method Services that supports the features you 
desi re. 

2. Export (with the PERMANENT attribute) all VSAM data sets 
from the old master catalog. Ignore for the moment the 
storage index and page data sets in the old master catalog. 

3. Mount a scratch pack to hold a temporary catalog, a storage 
index, and the page data sets. 

4. Define a temporary master catalog on the scratch pack. You 
can specify either DEFINE MASTERCATALOG or DEFINE 
USERCATALOG. In either case, VSAM creates a user catalog 
which can then be referenced in step 6 and used for the IPL 
i n step 7 . 

5. Catalog the nonVSAM data sets needed for an IPL on the 
temporary master catalog. Define a new storage index and 
page data sets on the scratch volume in the temporary 
catalog. The page data sets should have the same name as the 
original page data sets so that the IEASYSOO member in 
SYS1.PARMLIB need not be replaced. 

6. Alter the SYSCATLG member of the SYS1. NUCLEUS data set so 
that it points to the temporary catalog. 

7. IPL the system (cold start procedure). The system now is 
using the temporary catalog as the master catalog, and 
refers to the storage index data set and page data sets 
cataloged in the temporary catalog. 

8. Use the ALTER REMOVEVOLUMES command to remove VSAM from the 
volumes containing the old master catalog, the old page data 
sets, and the old storage index, and to remove VSAM from any 
volumes owned by the old master catalog. 

9. Define the new catalog in place of the original. This 
catalog will eventually become the VSAM master catalog. As 
in step 4, you can specify either DEFINE MASTERCATALOG or 
DEFINE USERCATALOG. 

10. Redefine the storage index and page data sets in their 
original locations on the new master catalog. (Allow room 
for the catalog recovery area if the new catalog has been 
defined with the recoverable attribute.) Catalog all nonVSAM 
data sets needed for IPL in the new master catalog. 

11. Replace the SYSCATLG member in SYS1. NUCLEUS (now cataloged 
in the new master catalog) so that the SYSCATLG member 
points to the new master catalog. 

12. RelPL the system (a cold start). The system should now be 
using the new VSAM master catalog, the redefined storage 
index, and the newly defined page data sets. 

13. Clean up the scratch pack using the ALTER command with the 
REMOVEVOLUMES parameter. 
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14. Recatalog all the remaining nonVSAM data sets into the new 
master catalog. 

15. Connect (and define aliases for) OS catalogs (CVOLs) that 
were connected to the old master catalog. 

16. Redefine the data spaces that Mere deleted from the old 
master catalog. 

17. Import the previously exported VSAM data sets into the new 
master catalog. 

18. Import (with the CONNECT parameter) and define aliases for 
user catalogs that were connected to the old master catalog. 

Your new master catalog is now reestablished. In this example, 
the new master catalog is recoverable (that is, its volume 
includes a catalog recovery area and can be processed with the 
LISTCRA, EXPORTRA, IMPORTRA, and RESETCAT commands). 

Figure 32 shows an example of the job stream needed to make your 
master catalog a recoverable catalog. The step numbers in the 
jobs correspond to the steps described previously. 

If your old master catalog is already recoverable, you can use 
the EXPORTRA and IMPORTRA commands rather than the EXPORT and 
IMPORT commands as used in this example. You can use EXPORTRA 
for all volumes owned by the master catalog, including the 
master catalog volume, in place of step 2 above. After 
redefining any VSAM data spaces (step 16), you can use IMPORTRA 
in place of steps 14, 15, 17, and 18. 
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INSTALL VSAM ON YOUR SYSTEM 

PGM=IDCAMS 

SYSOUT=A 
statements that describe the output data sets 

* 
commands required to export 
connector entries from the 



the 
old 



//J0B1 JOB . . . 
//* STEP 1 - 
//STEP2 EXEC 
//SYSPRINT DD 
//* DD 
//SYSIN DD 
EXPORT 
catalog 
/X 

//* STEP 3 - MOUNT A SCRATCH PACK 
//STEP4 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//CATPAK DD UNIT=3330,VOL=SER=CATPAK,DISP=OLD 
//SYSIN DD x 

DEFINE MASTERCATALOG - 

(NAMECTEMPCAT) - 

FILE(CATPAK) - 

VOLUMECCATPAK) - 

CYLINDERS (12 1)) 
/x 

//STEP5 EXEC PGM=IDCAMS,COND=C0,LT) 
//STEPCAT DD DSN=TEMPCAT, DISP=0LD 
//SYSPRINT DD SYSOUT=A 

//CATPAK DD UNIT=3330,VOL=SER=CATPAK,DISP=OLD 
//SYSIN DD x 



VSAM data se 
master catal 



ts and user 
og 



DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 

DEF CATCTEMPCAT) NVSAM 
DEF CLUSTER - 

CNAMECSYS1.STGINDEX) 

FILE CCATPAK) 

KEYSC12,8) - 

CYLINDERS (6,0) - 

RECORDSIZEC2041,2041) - 

VOLUMECCATPAK) - 

UNIQUE) - 

DATA C CONTROL INTERVALSIZEC 2048)) 

CATALOGCTEMPCAT) 



CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1 

CNAMECSYS1.HELP ) 

CNAMECSYS1.SAMPLIB 



LPALIB ) VOLCSG2001) 
LINKLIB ) VOLCSG2001 
DSSVM ) VOLCSG2001) 
SVCLIB ) VOLCSG2001) 
NUCLEUS ) VOL(SG2001 



DCMLIB 
INDMAC 
CMDLIB 
CMDLIB 



) VOL(SG2001) 
) VOL(SG2001) 
) VOL(SG2001) 
) VOL(SG2001) 
VOL(SG2001) 
) VOLCSG2001 



CNAMECSYS1.MACLIB ) VOLCSG2001) 
CNAMECSYS1.PROCLIB ) VOLCSG2001 
CNAMECSYS1.TELCMLIB ) VOLCSG200 
CNAMECSYS1.UADS ) VOLCSG2001) 
CNAMECSYS1.VTAMLIB ) VOL(SG2001 
(NAME(SYS1.IMAGELIB ) VOLCSG200 
CNAMECSYS1.PARMLIB ) VOLCSG2001 
CNAMECSYS1.BRODCAST ) VOLCSG200 



CNAMECSYS1.MANX ) 
CNAMECSYS1.MANY ) 
CNAMECSYS1.DUMP00 
CNAME(SYS1.DUMP01 
(NAME(SYSl.LOGREC 



VOL(SG2001) 
VOL(SG2001) 



VOL(SG2001) 
VOL(SG2001) 
VOL(SG2001) 



DEV(3330)) 
) DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
) DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
) DEVTC3330)) 

DEVTC3330)) 
) DEVTC3330)) 
1) DEVTC3330)) 
DEVTC3330)) 
) DEVTC3330)) 
1) DEVTC3330)) 
) DEVTC3330)) 
1) DEVTC3330)) 
DEVT(3330)) 
DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 
DEVTC3330)) 



Figure 32 (Part 1 of 4). 



Sample Job Stream to Make the Master Catalog 
Recoverable 
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DEFINE PAGESPACE - 

(NAME(SPOOLIPI) - 

FILECCATPAK) - 

CYLINDERS(80) - 

VOLUME(CATPAK) - 

UNIQUE) - 

CATALOG(TEMPCAT) 
DEFINE PAGESPACE - 

(NAME(SP00L1P2) - 

FILECCATPAK) - 

CYLINDERS(40) - 

VOLUME(CATPAK) - 

UNIQUE) - 

CATALOG(TEMPCAT) 
/x 

//STEP6A EXEC PGM=IEHPROGM, COND=(0 , LT) 
//SG2001 DD DISP=OLD,VOL=SER=SG2001,UNIT=3330 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 

SCRATCH DSNAME=SYS1. NUCLEUS, VOL=3330=SG2001 ,MEMBER=SYSCATLG 
/x 

//STEP6B EXEC PGM=IEBGENER, COND=( , LT) 
//SYSIN DD DUMMY 
//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=SYSl.NUCLEUS(SYSCATLG),DISP=(OLD,KEEP)> 
// DCB=BLKSIZE=13030,VOL=SER=SG20 01,UNIT=333 
//SYSUT1 DD x 

CAPAK (See Note 1) 
/x 

//* STEP 7 - IPL THE SYSTEM 
// 

//J0B2 JOB ... 
//STEP8 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//DD3330 DD UNIT=3330 , DISP=OLD, VOL=SER=(SG2001 >SPOOLl ) 
//SYSIN DD x 

ALTER TEMPCAT RVOL ( SG2001 SPOOL1) FILE ( DD3330 ) 
/x 

//STEP9 EXEC PGM=IDCAMS,COND=(0,LT) 
//SYSPRINT DD SYSOUT=A 

//SG2001 DD UNIT=3330,VOL=SER=SG2001,DISP=OLD 
//SYSIN DD X 

Figure 32 (Part 2 of 4). Sample Job Stream to Make the Master Catalog 

Recoverable 
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DEFINE MASTERCATALOG - 

(NAME(AMASTCAT) - 

FILECSG2001) - 

VOLUMECSG2001) - 

CYLINDERS (12 1) - 

RECOVERABLE) 
/* 

//STEP10 EXEC PGM=IDCAMS,COND=(0,LT) 
//STEPCAT DD DSN=AMASTCAT , DISP=OLD 
//SYSPRINT DD SYSOUT=A 

//SPOOL1 DD UNIT=3330,VOL=SER=SPOOL1,DISP=OLD 
//SG2001 DD UNIT=333Q,VOL=SER=SG2001,DISP=OLD 
//SYSIN DD * 
DEF CLUSTER - 

(NAME(SYSl.STGINDEX) - 

FILE (SG20Q1) - 

KEYS(12,8) - 

CYLINDERS(6,0) - 

RECORDSIZE(2041,2041) - 

VOLUMECSG2001) - 

UNIQUE) - 

DATACCONTROLINTERVALSIZE (2048)) - 

CATALOG(AMASTCAT) 
DEFINE PAGESPACE - 

(NAME(SPQOLIPI) - 

FILE(SPOOLl) - 

CYLINDERS(140) - 

VOLUME(SPOOLl) - 

UNIQUE) - 

CATALOG(AMASTCAT) 
DEFINE PAGESPACE - 

(NAME(SP00L1P2) - 

FILE(SPOOLl) - 

CYLINDERS(40) - 

VOLUME(SPOOLl) - 

UNIQUE) - 

CATALOG(AMASTCAT) 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . LPALIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . LINKLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . DSSVM ) 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . SVCLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 .NUCLEUS 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . DCMLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . INDMAC 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . CMDLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . HELP ) 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . SAMPLIB 
DEF CAT(AMASTCAT) NVSAM (NAMECSYS1 .MACLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 .PROCLIB 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . TELCMLI 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 .UADS ) 
DEF CAT(AMASTCAT) NVSAM (NAME(SYS1 . VTAMLIB 



) VOL(SG2001 

) VOL(SG200 

VOL(SG2001) 

) VOL(SG2001 

) VOL(SG20 

) VOL(SG2001 

) VOL(SG2001 

) VOL(SG2001 

VOL(SG2001) 

) VOL(SG200 

) VOL(SG2001 

) VOL(SG200 

B ) VOL(SG20 

VOL(SG2001) 

) VOL(SG200 



) DEVK3 
1) DEVT( 
DEVK33 
) DEVTC3 
1) DEVT( 
) DEVTC3 
) DEVTC3 
) DEVTC3 
DEVK333 
1) DEVT( 
) DEVTC3 
1) DEVT( 
01) DEVT 
DEVTC333 
1) DEVT( 



330)) 

3330)) 

30)) 

330)) 

3330)) 

330)) 

330)) 

330)) 

0)) 

3330)) 

330)) 

3330)) 

(3330)) 

0)) 

3330)) 



Figure 32 (Part 3 of 4). 



Sample Job Stream to Make the Master Catalog 
Recoverable 
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DEF CATCAMASTCAT) NVSAM CNAMECSYS1 . IMAGELIB ) VOLCSG2001) DEVTC3330)) 
DEF CAT(AMASTCAT) NVSAM CNAMECSYS1 .PARMLIB ) VOLCSG2001) DEVTC3330)) 
DEF CATCAMASTCAT) NVSAM CNAMECSYS1 . BRODCAST ) VOLCSG2001) DEVTC3330)) 
DEF CATCAMASTCAT) NVSAM CNAMECSYS1 .MANX ) VOLCSG2001) DEVTC3330)) 
DEF CATCAMASTCAT) NVSAM (NAMECSYS1 .MANY ) VOUSG2001) DEVTC333Q)) 
DEF CATCAMASTCAT) NVSAM CNAMECSYS1 . DUMPOO ) VOLCSG2001) DEVTC3330)) 
DEF CATCAMASTCAT) NVSAM CNAMECSYS1 . DUMPOl ) VOLCSG2001) DEVTC3330)) 
DEF CATCAMASTCAT) NVSAM CNAMECSYS1 . LOGREC ) VOLCSG2001) DEVTC3330)) 

/* 

//STEP11A EXEC PGM=IEHPROGM,COND=CO,LT) 

//SG2001 DD DISP=OLD,VOL=SER=SG2Q01,UNIT=3330 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

SCRATCH DSNAME=SYS1. NUCLEUS, VOL =3330 =SG20 01,MEMBER=SYSCATLG 

/* 

//STEP11B EXEC PGM=IEBGENER,COND=C0,LT) 

//SYSIN DD DUMMY 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=SYS1.NUCLEUSCSYSCATLG),DISP=C0LD,KEEP), 

// DCB=BLKSIZE=130 30,VOL=SER=SG20 01,UNIT=3330 

//SYSUT1 DD x 

SG2001 CSEE NOTE 1) 

/x 

// 

//J0B3 JOB ... 

//X STEP 12 - REIPL THE SYSTEM 

//STEP13 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//CATPAK DD UNIT=3330,VOL=SER=CATPAK,DISP=OLD 

//SYSIN DD x 

ALTER AMASTCAT - 
FILECCATPAK) - 
REMOVEVOLUMESC CATPAK) 

/x 

// 

Notes: 

1. This data record has the volume serial number of the volume containing the 
alternate catalog in columns 1 to 6. 

Figure 32 CPart 4 of 4). Sample Job Stream to Make the Master Catalog 

Recoverable 



Appendix H. Changing the Attributes of the VSAM Master Catalog 485 



GLOSSARY 



The following terms are defined as 
they are used in this book. If you do 
not find the term you are looking for, 
refer to the index or to the Data 
Processing Glossarv > GC20-1699. 

Access Method services: A 

multifunction service program that 
defines VSAM data sets and allocates 
space for them, converts 
i ndexed-sequent i al data sets to 
key-sequenced data sets with indexes, 
modifies data-set attributes in the 
catalog, reorganizes data sets, 
facilitates data portabi li ty between 
operating systems, creates backup 
copies of data sets and indexes, helps 
make inaccessible data sets 
accessible, and lists the records of 
data sets and catalogs. 

addressed direct access: The retrieval 
or storage of a data record identified 
by its RBA, independent of the 
record* s location relative to the 
previously retrieved or stored record. 
( See also keyed direct access, 
addressed sequential access, and keyed 
sequential access.) 

addressed sequential address: The 

retrieval or storage of a data record 
in its entry sequence relative to the 
previously retrieved or stored record. 
( See also keyed sequential access, 
addressed direct access, and keyed 
di rect access. ) 

alias: An alternative name for an 
entry. 

alias entry: An entry that relates an 
alias (alternate entryname) to the 
real entryname of a user catalog or 
nonVSAM data set. 
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index: An ordered collection 
, each consisting of a key 
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ers. An alternate index is 
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index entry: A catalog entry 
ins information about an 
index. An alternate index is 
ly a key-sequenced cluster, 
aloged in the same way. An 
index entry points to a data 
an index entry to describe 
ate-index's components, and 
er entry to identify the 
index's base cluster. ( See 
er entry. ) 



alternate-index record: a collection 
of items used to sequeree and locate 
one or more data records in a base 
cluster. Each alternate-index record 
contains an alternate-key value and 
one or more pointers. When the 
alternate index supports a 
key-sequenced data set, each data 
record's prime key value i s the 
pointer. When the alternate index 
supports an entry-sequenced data set, 
the data record's RBA value is the 
pointer. ( See also alternate index, 
alternate key, base cluster, and key.) 

alternate key: One or more characters 
within a data record, used to identify 
the data record or control its use. 
Unlike the prime key, the alternate 
key can identify more than one data 
record. ( See also key and key field.) 

application: As used in this 
publication, the use to which an 
access method is put or the end result 
that it serves; contrasted to the 
internal operation of the access 
method. 

backup data set: A copy that can be 
used to replace or reconstruct a 
damaged data set. 

base cluster: The VSAM cluster whose 
data records are to be accessed 
through a path. Usually, a base 
cluster is the key-sequenced or 
entry-sequenced data set which an 
alternate index supports (that is, an 
alternate index is used by VSAM to 
sequence and locate the data records 
of a base cluster). ( See also 
alternate index and path.) 

bind: (verb) To keep a data set that 
has been staged from a mass-storage 
volume to a direct-access storage 
staging drive on the staging drive 
until the data set is closed. 

catalog: ( See master catalog and user 
catalog.) 

catalog cleanup: A process that allows 
you to delete entries if their volume 
is no longer available; catalog 
cleanup also allows you to delete a 
catalog even though it is not empty. 
Catalog cleanup is a function of the 
DELETE command. 

catalog connector: A catalog entry, 
called either a user catalog entry or 
a catalog connector entry, in the 
master catalog that points to a user 
catalog's volume (that is, it contains 
the volume serial number of the 
direct-access volume that contains the 
user catalog). 
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catalog recovery area: ( See CRA.) 

Cluster: A data component and an index 
component when data is key sequenced; 
a data component alone when data is 
entry sequenced. 

Cluster entry: A catalog entry that 
contains information about a 
key-sequenced or entry-sequenced VSAM 
cluster: ownership* cluster 
attributes, and the cluster's 
passwords and protection attributes. A 
key-sequenced cluster entry points to 
a data entry and an index entry. An 
entry-sequenced cluster entry points 
to a data entry. 

collating sequence: An ordering 
assigned to a set of items, such that 
any two sets in that assigned order 
can be collated. As used in this 
publication, the order defined by the 
System/370 8-bit code for alphabetic, 
numeric, and special characters. 

component: The data portion or, for a 
key-sequenced cluster, alternate 
index, or VSAM catalog, the index 
portion or a VSAM object. In this 
book, the components of an object are 
usually referred to as the object's 
data component and index component. 

compression: ( See key compression.) 

control area: A group of control 
intervals used as a unit for 
formatting a data set before adding 
records to it. Also, in a 
key-sequenced data set, the set of 
control intervals pointed to by a 
sequence-set index record; used by 
VSAM for distributing free space and 
for placing a sequence-set index 
record adjacent to its data. 

control-area split: The movement of 
the contents of some of the control 
intervals in a control area to a newly 
created control area, to make possible 
the insertion or lengthening of a data 
record when a free control interval 
was needed and there was none in the 
original control area. 

control interval: A fixed-length area 
of auxiliary-storage space in which 
VSAM stores records and distributes 
free space. It is the unit of 
information transmitted to or from 
auxiliary storage by VSAM. 

control interval access: The retrieval 
and storage of a VSAM data-set's 
contents, based on the RBA of a 
control interval (that is, the user's 
program processes a control interval, 
rather than a data record, as a 
logi cal enti ty) . 

control-interval split: The movement 
of some of the stored records in a 
control interval to a free control 



interval, to make possible the 
insertion or lengthening of a record 
that won't fit in the original control 
i nterval . 

CRA: Catalog recovery area. An 
entry-sequenced data set that exists 
on each volume owned by a recoverable 
catalog, including the volume on which 
the catalog resides. The CRA contains 
copies of the catalog's records, and 
can be used to recover a damaged 
catalog. 

data component: That part of a VSAM 
data set, alternate index, or catalog 
that contains the object's data 
records. 

data entry: A catalog entry that 
describes the data component of a 
cluster, alternate index, page spaces, 
or catalog. A data entry contains the 
data component's attributes, 
allocation and extent information, and 
statistics. A data entry for a 
cluster's or catalog's data component 
can also contain the data component's 
passwords and protection attributes. 

data integrity: Preservation of data 
or programs for their intended 
purpose. As used in this publication, 
the safety of data from inadvertent 
destruction or alteration. 

data record: A collection of items of 
information from the standpoint of its 
use in an application, as a user 
supplies it to VSAM for storage. 

data security: Prevention of access to 
or use of data or programs without 
authorization. As used in this 
publication, the safety of data from 
unauthorized use, theft, or purposeful 
destructi on . 
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data space: A storage area defined in 
the volume table of contents of a 
direct-access volume for the exclusive 
use of VSAM to store data sets, 
indexes, and catalogs. 

destage: (verb) To transmit data from 
a direct-access storage staging drive 
to a mass-storage volume. 

direct access: The retrieval or 
storage of data by a reference to its 
location in a data set rather than 
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relative to the previously retrieved 
or stored data. ( See also addressed 
direct access and keyed direct 
access. ) 

distributed free space: Space reserved 
within the control intervals of a 
key-sequenced data set for inserting 
new records into the data set in key 
sequence; also, whole control 
intervals reserved in a control area 
for the same purpose. 

dynamic allocation: The allocation of 
a data set or volume by the use of the 
data set name or volume serial number 
rather than by the use of information 
contained in a JCL statement. 

entry: A collection of information 
about a cataloged object in a VSAM 
master or user catalog. Each entry 
resides in one or more 512-byte 
record. 

entry name: A unique name for each 
component or object as it is 
identified in a catalog. The entryname 
is the same as the dsname i n a DD 
statement that describes the object. 

entry sequence: The order in which 
data records are physically arranged 
(according to ascending RBA) in 
auxiliary storage, without respect to 
their contents. ( Contrast to key 
sequence. ) 

entry-sequenced data set: A data set 
whose records are loaded without 
respect to their contents, and whose 
RBAs cannot change. Records are 
retrieved and stored by addressed 
access, and new records are added at 
the end of the data set. 

exception: An abnormal condition such 
as an I/O error encountered in 
processing a data set. 
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before the SYNAD exit 
control. The 
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extent: A continuous space allocated 
on a direct-access storage volume, 
reserved for a particular data space 
or data set. An extent of a data set 
contains a whole number of control 
areas. 

external sort: Sorting of data records 
into a new sequence using a small 
amount of virtual storage and two 



temporary sortf i les (entry-sequenced 
data sets) on a direct-access storage 
volume. ( See also internal sort.) 

field: In a record or a control block, 
a specified area used for a particular 
category of data or control 
information. 

free space: ( See distributed free 
space. ) 

generation data group entry: An entry 
that permits nonVSAM data sets to be 
associated with other nonVSAM data 
sets as generation data sets. 

generation data set: One of a 
collection of historically related 
nonVSAM data sets; the collection of 
these data sets i s known as a 
generation data group. 

generic key: A high-order portion of a 
key, containing characters that" 
identify those records that are 
significant for a certain application. 
For example, it might be desirable to 
retrieve all records whose keys begin 
with the generic key AB, regardless of 
the full key values. 

generic name: A qualified name in 
which one qualifier i s replaced by an 
asterisk; the generic name applies to 
all entries that match the qualifiers 
supplied in the generic name. 

horizontal pointer: A pointer in an 
index record that gives the location 
of another index record in the same 
level that contains the next key in 
collating sequence; used for keyed 
sequential access. 

index: As used in this publication, an 
ordered collection of pairs, each 
consisting of a key and a pointer, 
used by VSAM to sequence and locate 
the records of a key-sequenced data 
set; organized in levels of index 
records. ( See also index level, index 
set, and sequence set.) 

index component: That part of a 
key-sequenced data set, catalog, or 
alternate index, that establishes the 
sequence of the data records within 
the object it indexes. The index is 
used to locate each record in the 
object's data component, based on the 
record's key value. 

index entry: A catalog entry that 
describes the index component of a 
key-sequenced cluster, alternate 
index, or catalog. An index entry 
contains the index component's 
attributes, passwords and protection 
attributes, allocation and extent 
information, and statistics. 
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index level: A set of index records 
that order and give the location of 
records in the next lower level or of 
control intervals in the data set that 
it controls. 

index record: A collection of index 
entries that are retrieved and stored 
as a group. ( Contrast to data record.) 

index replication: The use of an 
entire track of direct-access storage 
to contain as many copies of a single 
index record as possible; reduces 
rotational delay. 

index set: The set of index levels 
above the sequence set. The index set 
and the sequence set together comprise 
the index. 

index upgrade: The process of updating 
an alternate index to reflect the 
changes made to the contents of its 
base cluster. 

integrity: ( See data integrity.) 

internal sort: Sorting of data records 
into a new sequence using virtual 
storage and no temporary data sets on 
a direct-access storage device. ( See 
also external sort.) 

ISAM interface: A set of routines that 
allow a processing program coded to 
use ISAM (indexed sequential access 
method) to gain access to a 
key-sequenced data set with an index. 

job catalog: A catalog made available 
for a job/ by means of a JOBCAT DD 
statement, or for a job step, by means 
of a STEPCAT DD statement. 

key: One or more characters within an 
item of data that. are used to identify 
it or control its use. As used in this 
publication, one or more consecutive 
characters taken from a data record, 
used to identify the record and 
establish its order with respect to 
other records. ( See also key field and 
generi c key. ) 

key compression: The elimination of 
characters from the front and the back 
of a key that VSAM does not need to 
distinguish the key from the preceding 
or following key in an index record; 
reduces storage space for an index. 

key field: A field located in the same 
position in each record of a data set, 
whose contents are used for the key of 
a record. 

key sequence: The collating sequence 
of data records, determined by the 
value of the key field in each of the 
data records. May be the same as, or 
different from, the entry sequence of 
the records. 



key-sequenced data set: a data set 
whose records are loaded in key 
sequence and controlled by an index. 
Records are retrieved and stored by 
keyed access or by addressed access, 
and new records are inserted in the 
data set in key sequence by means of 
distributed free space. RBAs of 
records can change. 

keyed direct access: The retrieval or 
storage of a data record by use of an 
index that relates the record's key to 
its relative location in the data set, 
independent of the record's location 
relative to the previously retrieved 
or stored record. ( See also addressed 
direct access, keyed sequential 
access, and addressed sequential 
access. ) 

keyed sequential access: The retrieval 
or storage of a data record in its key 
sequence relative to the previously 
retrieved or stored record, as defined 
by the sequence set of an index. ( See 
also addressed sequential access, 
keyed direct access, and addressed 
di rect access. ) 

mass sequential insertion: A technique 
VSAM uses for keyed sequential 
insertion of two or more records in 
sequence into a collating position in 
a data set** more efficient than 
inserting each record directly. 

mass storage volume: The unit of mass 
storage in the 3850 Mass Storage 
System. 

master catalog: A key-sequenced data 
set with an index containing extensive 
data-set and volume information that 
VSAM requires to locate data sets, to 
allocate and deallocate storage space, 
to verify the authorization of a 
program or operator to gain access to 
a data set, and to accumulate usage 
statistics for data sets. 

nonunique keys: An alternate key value 
in a base-cluster's data record that 
equals the alternate key value of 
another data record. When an alternate 
index is created such that it allows 
nonunique keys, more than one data 
record might be located with the same 
key value. 
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object I A logical entity created by 
VSAM, such as a cluster (VSAM data 
set) and its components, an alternate 
index and its components, a VSAM 
catalog and its components, a path, or 
a VSAM data space. 

page space: A VS2 system data set. A 
page space i s cataloged as an entry 
sequenced cluster (that is, the page 
space entry is similar to a cluster 
entry, and it points to a data entry). 

password: A unique string of 
characters stored in a catalog that a 
program or a computer operator at the 
console must supply to meet security 
requirements before the program gains 
access to a data set. 

path: A data set name for the 
combination of an alternate index and 
its base cluster, or an alias for a 
VSAM data set. 

path entry: A catalog entry that m 
contains information about a path, and 
that points to the path's related 
objects. 

physical record: On a track of a 
direct-access storage device, the 
space between interrecord gaps. 

pointer: An address or other 
indication of location. For example, 
an RBA is a pointer that gives the 
relative location of a data record or 
a control interval in the data set to 
which it belongs. ( See also horizontal 
pointer and vertical pointer.) 
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primary space allocation: Initially 
allocated space on a direct-access 
storage device, occupied by or 
reserved for a particular data set. 
( See also secondary space allocation.) 

prime index: The index component of a 
key-sequenced data set. ( See also 
index and alternate index.) 

prime key: ( See key.) 

qualified name: A name that is 
segmented by periods; each name 
segment is referred to as a qualifier. 

random access: ( See direct access.) 

RBA: Relative byte address. The 
di splacement of a data record or a 
control interval from the beginning of 



the data set to which it belongs; 
independent of the manner in which the 
data set is stored. 

record: ( See index record, data 
record, stored record.) 

record replacement: An enhancement of 
the REPRO command which allows the 
user to merge two data sets and, when 
duplicate records are found (that is, 
the key values of two records are 
equal) the data record from the source 
data set replaces the data record in 
the target data set. 

recoverable catalog: a catalog defined 
with the recoverable attribute. 
Duplicate catalog entries are put into 
CRAs that can be used to recover data 
in the event of catalog failure. ( See 
also CRA. ) 

recovery volume: The first volume of a 
prime index, if the VSAM data set is 
key-sequenced cluster; otherwise, the 
first volume of the data set, if ESDS. 

relative byte address: ( See RBA.) 

relative record: A data record whose 
position depends on its placement 
within a a group of data records; its 
position, or record number, is its 
displacement, in records, from the 
beginning of the data set. 

relative-record data set: A data set 
whose records are loaded into 
fixed-length slots. 

relative-record number: a number that 
identifies not only the slot, or 
record space, in a relative-record 
data set but also the record occupying 
the slot. 

replication: ( See index replication.) 

reusable data set: a VSAM data set 
that can be used as a workfile 
regardless of its old contents. 

secondary space allocation: A 

contiguous space* on a direct-access 
device, occupied by or reserved for a 
particular data set, which is 
allocated after space in the primary 
extent has been exhausted. ( See also 
primary space allocation.) 

security: ( See data security.) 

sequence checking: The process of 
verifying the order of a set of 
records relative to some field's 
collating sequence. 

sequence set: The lowest level of the 
index of a key-sequenced data set; it 
gives the locations of the control 
intervals in the data set and orders 
them by the key sequence of the data 
records they contain. The sequence set 
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and the index set together comprise 
the index. 

sequential access: The retrieval or 
storage of a data record in either its 
entry sequence or its key sequence* 
relative to the previously retrieved 
or stored record. ( See also addressed 
sequential access and keyed sequential 
access. ) 

simple name: A qualifier of a 
qualified entryname or dsname. Simple 
names may be one to eight characters 
and* in a series, are separated from 
each other by a period. 

skip sequential access: Keyed 
sequential retrieval or storage of 
records here and there throughout a 
data set, skipping automatically to 
the desired record or collating 
position for insertion: VSAM scans the 
sequence set to find a record or a 
collating position. 

slot: The space for a data record in a 
relative-record data set. 

sort: ( See external sort* internal 
sort* and collating sequence.) 

spanned record: A logical record whose 
length exceeds control interval 
length* and crosses (or spans) one or 
more control interval boundaries 
within a control area. 

Stage: (verb) To transmit data from a 
mass-storage volume to a direct-access 
storage staging drive. 



Step catalog: ( See job catalog.) 

Stored record: A data record* together 
with its control information* as 
stored in auxiliary storage. 

upgrade set: All the alternate indexes 
that VSAM has been instructed to 
update whenever there i s a change to 
the data component of the base 
cluster. 

user catalog: A catalog used in the 
same way as the master catalog* but 
optional and'pointed to by the master 
catalog* and also used to lessen the 
contention for the master catalog and 
to facilitate volume portability. 

user catalog connector: ( See catalog 
connector . ) 

vertical pointer: A pointer in an 
index record of a given level that 
gives the location of an index record 
in the next lower level or the 
location of a control interval in the 
data set controlled by the index. 

volume cleanup: The process of 
deleting all VSAM data spaces from a 
volume and removing a VSAM catalog's 
ownership of the volume* even though 
the volume contains VSAM data records. 

volume entry: A catalog entry that 
describes a volume owned by the 
catalog. All VSAM data spaces on the 
volume are described in the volume 
entry and the catalog is no longer 
avai laEfle. 



Glossary 491 



INDEX 



abbreviati ons, parameter 5,381 
Access Method Services commands 4 
functional 4 
modal 5 

guide to 1 

introduction to 4 

invoking 11 
access, read only 27,130,288 
accessibility to secondary extents 33 
adding records through the REPRO 

command 104 
adding volumes 123 
ADDVOLUMES parameter (ALTER) 123 
ALIAS parameter 64 

in DEFINE command 149 

in DELETE command 272 

in LISTCAT command 317 
ALL parameter (LISTCAT) 318 

example of output 422 
ALL subparameter (EXPORTRA) 293 
ALL subparameter (RESETCAT) 350 
allocating space 

by range of key values 195 

for a catalog 51 

on unmounted volumes 46 
allocat i on 

dynamic 9,46 

of a catalog recovery area (CRA) 57 

of a volume 16 

of catalog's space 51 

of user catalogs 21 
ALLOCATION parameter (LISTCAT) 318 

example of output 429 

( see also BUFFERSPACE parameter) 
ALTER command 71,119 

allocation parameters 119 

alternate index and path 
attributes 119 

catalog parameter 125 

entry types to which each parameter 
applies 121 

examples 136 

format 119 

generation-data-group attribute 
parameters 119 

name parameters 119 

parameter summary table 121 

order of catalog use 72 

Parameters 123 

Optional parameters 123 
Required parameters 123 

protection and integrity 
parameters 119 

removing VSAM ownership of a 
volume 16,36 

volume cleanup 36,73 
altering catalog entries 71 
alternate index 

backing up (copying) 104 

building 67 

defining 61,151 

deleting 77,272 

exporting 84 

importing 84 

listing its catalog entry 75 

printing its contents 114 



alternate name 
creating 64,149 

examples 151 
deleting 77,272 
example 282 
alternate output data sets 11 
ALTERNATEINDEX parameter 61 
in DEFINE command 151 
in DELETE command 272 
in LISTCAT command 317 
amendments, summary of vi i 
AN, print chain option 362 
AREAS parameter (PARM) 362 
ATTEMPTS parameter 30 
in ALTER command 123 
in DEFINE command 
ALTERNATEINDEX 160 
Catalog 254 
CLUSTER 190 
PAGESPACE 231 
PATH 241 
USERCATALOG 254 
note for TSO users 254 
attributes 58 
altering 71 
changing 71,482 
defining 46,58 
nullifying 131 
AUTHORIZATION parameter 
in ALTER command 124,129 
in DEFINE command 
ALTERNATEINDEX 160 
CLUSTER 190 
PAGESPACE 231 
PATH 242 
USERCATALOG 254 
nullifying 129 
Auxiliary Storage Management 235 
authorization to process a data set 
passwords 27 
RACF protection 31 
use i — securi ty-veri f i cat i on 
routine 31 



backing up catalogs 35 
backing up data sets 32,104 
beginning location 

in PRINT command 329 

in REPRO command 338 
BIND parameter 25 

in ALTER command 133 

in DEFINE command 

used to define an alternate 

index 173 
used to define a cluster 204 
blanks vi ,6 
BLDINDEX command 67,138 

catalog parameter 138 

DD statements that describe the SORT 
workfiles 69 

example 141 

format 138 

how an alternate index is built 67 

order of catalog use 69 

parameters 138 



492 0S/VS2 Access Method Services 



so 

bold 

con 

brae 

brae 

BUFF 

i n 

i n 



buil 



Opti onal 
Requi red 
rt param 

face ty 
vent l ons 
es> inn 
kets, in 
ERSPACE 

ALTER c 

DEFINE 
used to 

i ndex 
used to 
used to 
ding an 



parameters 138 

parameters 138 
eters 69 
pe, in notation 

vi 
otation conventions vi 

notation conventions 
parameter 
ommand 124 
command 

define an alternate 
161 

define a catalog 256 
define a cluster 191 
alternate index 67,138 



vi 






calculating space for a catalog 51 
CALL macro, invoking Access Method 

Services with 14,475 
CANDIDATE parameter (DEFINE 

SPACE) 250 
capitalization, in notation 

conventions vi 
catalog 

( see also master catalog and user 

catalog) 
allocating user catalogs 51 
altering 71,119 
backing up 35,111 
calculating space for 54 
cleanup 38 
connecting to master catalog 

(IMPORT) 82,299 
converting devices 104 
creating 253 
defining 51 
di splay i ng 75 
dumping a 35 

duplicate names, preventing 46 
entries, moving 82 
identifying the volume of a 54 
1 i st i ng 75 
master 20 
modifying 71 
order of use 
ALTER' 72 
BLDINDEX 69 
DEFINE 47 
DELETE 80 
LISTCAT 75 
OS CVOLs (control volumes) 22 
OS entries, converted to VSAM 

entries 23,86 
ownership of a volume 16,36 
preventing duplicate names 46 
protecting 34 
recovery 39,93 
relationships among 21 
reloading 112 

resetting catalog entries 98 
restoring the entries after system 

failure 35,93 
secondary allocation amount 56 
setting up the master catalog 20 
space estimates 54 
space, allocation of 51 
transporting user catalogs 38 
unloading 112 
update password and nonVSAM data 
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checkpoint 116 
parameters 142 

optional parameters 142 
required parameters 142 
sample output from 455 
CHKPT JCL parameter 438 
cleanup 

catalog 38,270 
volume 36 
cluster 

backing up (copying) 32,104 
defining 58,182 
deleting 77,270 
exporting 82,286 
extending volumes xxxx 
listing its entry 75,316 
importing 82,299 
printing its contents 114,327 
verifying its end-of-f i le 
values 91,356 
CLUSTER parameter 

in DEFINE command 182 
in DELETE command 272 
in LISTCAT command 317 
cluster type, specifying 184 
CNVTCAT command 86,145 
examples 146 
format 145 
parameters 145 
CODE parameter 29 

in ALTER command 125 
in DEFINE command 
ALTERNATEINDEX 161 
CATALOG 256 
CLUSTER 191 
PAGESPACE 232 
PATH 243 
USERCATALOG 256 
nullifying 129 
command continuation 7 
command execution, controlling 358 
command reference summary 455 
command statement syntax 5 
commands 

ALTER 71,119 
BLDINDEX 67,138 
CHKLIST 116,142 
CNVTCAT 86,145 
continuation of 7 
DEFINE 

ALIAS 64,149 
ALTERNATEINDEX 61,151 
CLUSTER 58,182 

for an entry-sequenced 

cluster 189 
for a key-sequenced 

cluster 186,189 
for a relative-record 
cluster 189 
GENERATIONDATAGROUP 65,218 
NONVSAM 64,223 
PAGESPACE 65,228 



PATH 63,240 
SPACE 57,249 
USERCATALOG 51,253 

DELETE 77,270 

DO 5, 360 

END 5,360 

EXPORT 82,286 

EXPORTRA 93,293 

functional 4 

general structure 5 

guide to 1 

IF 5,359 

IMPORT 82,299 

IMPORTRA 93,309 

introduction 4 

LISTCAT 75,316 

LISTCRA 95,324 

modal 5,358 

not allowed under TSO 13 

parameter set 5 

reference summary 455 

PARM 5,361 

PRINT 114,327 

REPRO 104,337 

RESETCAT 98,350 

SET 361 

VERIFY 91,356 

structure of 5 

terminator 8 

types 4 
commas 6 
comments 6 
COMPARE parameter (LISTCRA) 325 

example of output 453 
components parameters (DEFINE) 

used to define an alternate 
index 176 

used to define a catalog 262 

used to define a cluster 206 
concatenated DD statements 9 
condition codes 358 
conditional command execution 

using LASTCC 361 

using MAXCC 361 
conditional statements 358 
CONNECT parameter (IMPORT) 299 
connecting a user catalog to the 

master catalog 20,64,82 
considerations, language 5 

continuation cautions 7 

continuing commands 7 

for multi volume data sets 
(RESETCAT) 101 

job control language 9 

parameter set 5 

terminator 8 
continuation of commands 7 
control-access password 27 

( see also CONTROLPW parameter) 
control*" area 

in catalogs 51 

Preformatting 32 
control volume pointer entries, 

converted 22,86 
control volumes, OS 20,86 

converting to VSAM catalogs 86 

relationship to other catalogs 20 
CONTROLINTERVALSIZE parameter (DEFINE) 

used to define an alternate 
index 162 

used to define a cluster 192 
controlling command execution 358 
CONTROLPW parameter 

in ALTER command 125 



494 0S/VS2 Access Method Services 



in ALTER command (NULLIFY) 129 
in DEFINE command 
ALTERNATEINDEX 162 
CLUSTER 193 
PAGESPACE 232 
PATH 243 
USERCATALOG 258 
nullifying 129 
convent i ons 
notat i on vi 
syntactical 5 
converting catalog entries 86 
converting data sets 104 
converting devices for a user 

catalog 104 
copyi ng 

alternatei ndexes 29,104 
catalogs 110 
example 344 
for backup 35,111 
for device conversion 104 
example 344 
data sets 1,104 

from the catalog recovery area 95 
copying and printing, example of 375 
correcting end-of-data-set 

information 91 
correcting end-of-key-range 

information 91 
corrective measures 

for catalog integrity 40 
for data integrity 34 
COUNT parameter 

in PRINT command 331 
in REPRO command 341 
CRA ( see catalog recovery area) 
CRA parameter (EXPORTRA) 293 
CRAFILES parameter (RESETCAT) 350 
CRAVOLUMES parameter (RESETCAT) 350 
creat i ng 

alias names 64,149 

alternate indexes 67,138 

an alternate index and path, example 

of 383 
catalogs 51,253 
clusters 58,153,156 
data sets 58,64,182 
data spaces 57,249 
entry-sequenced data sets 58 
generation data groups 65,218 
key-sequenced data sets 58 
master catalog 51,253 
nonVSAM data sets 64 
page spaces 65,228 
path 63,240 
portable data sets 82 
user catalogs 51,253 
CREATION parameter (LISTCAT) 319 

example of output 434 
cross-region sharing 200 
cross-system sharing 200 
CVOLEQUATES parameter (CNVTCAT) 145 
CVOLs (control volumes), OS 22,86 
converting to VSAM catalogs 86 
relationship to other catalogs 21 
CYLINDERFAULT parameter 25 
in ALTER command 134 
in DEFINE command 

used to define an alternate 

index 173 
used to define a cluster 204 
CYLINDERS parameter 

used to define an alternate 
index 157 



used to define a cluster 187 

used to define a data space 250 

used to define a page space 229 

used to define a user catalog 253 



data, storage of 15 
data integrity 

backing up data 32 
data organization, specifying 189 
DATA parameter 

in DEFINE command 
ALTERNATEINDEX 176 
CATALOG 262 
CLUSTER 206 
USERCATALOG 263 

in LISTCAT command 317 
data portability 21,33,82 
data protection 32 
data security 

and protection 27 

authorization routine 14,27,31 

passwords 27 
data set 

allocation 46 

backup copy 32,82,104 

catalog entry 45 

cataloging 45,58,64 

copying 33,104 

comparison between types of 87 

creating 40,58,64 

defining 40,58,64 

deleting 77 

entry-sequenced 58 

generated names 17 

generation 218 

key-sequenced 58 

1 i st i ng 114 

loading records into 111 

NONVSAM 64 

organization 17,189 

output 11 

portability 33,82 

Preformatting 32 

reorganizing 112 

tape, open at checkpoint 116 

transporting 32,82 

unique 51,205,212 

using qualified names that identify 
the catalog 20,22 
data-set access 288 
data-set security bits in Format-1 

DSCB 17 
data-set type, specifying 64,189 
data space 

allocating the volume for 57,249 

defining 249 
examples 251 

extending 249 

pagespace in 228 

VSAM objects in a 16,58 
data sets, VSAM 16,58 
data spaces on a volume 16 
data structure, VSAM 15 
DATASET parameter (VERIFY) 356 
DD statements 6 ( see JCL) 

for Access Method Services jobs 10 

for JOBCAT and STEPCAT 
catalogs 21,46 

for output data sets 11 



Index 



495 



for RESETCAT work file 101 
for the BLDINDEX sort workfiles 69 
debugging tool 361 
default margins 5 
default output data set 11 
define a user catalog, example of 365 
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to define a page space 233 
to define a path 244 
to define a user catalog 258 
in DELETE command 274 
in VERIFY command 357 
FILE subparameter 

in IMPORT command 303 
in IMPORTRA command 312 
FILESEQUENCENUMBERS parameter (DEFINE 

NONVSAM) 224 
FOR parameter 

in ALTER command 134 
in DEFINE command 
ALTERNATEINDEX 174 
catalog 261 
CLUSTER 205 

GENERATIONDATAGROUP 218 
NONVSAM 226 
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LISTCRA NAME COMPARE output 452 
LISTCRA NAME NOCOMPARE output 448 
listing catalog entries 75 
examples of 323 
examples of output 414 
listing tape volumes mounted at 

checkpoint 116 
listing the catalog recovery area's 
contents 95 
examples of output 441 
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loading catalogs (unload/ reload) 112 
loading records into a data set 106 

Preformatting control areas 32 

REPRO command 338 
loading VSAM data sets 106 
lower case/ in notation 

conventions vi 
LRECL 104 
LT (less than) 360 



259 



making a copy of a data set 33 

making a user catalog available 21 

MARGINS parameter (PARM) 363 

margins, default 6 

Mass Storage System, IBM 3860 25 

mass storage volume 25 

master catalog 20 

( see also user catalog) 
backing up 111 

cataloging nonVSAM data sets 64 
changing the attributes of 535 
creating a 51 
deleting restriction 78 
improving availability of 35 
order of catalog search 
ALTER 72 
BLDINDEX 69 
DEFINE 47 
DELETE 80 
LISTCAT 75 
preventing duplicate names in 46 
protecting 34 
reloading 112 

relationship to user catalogs 19,51 
unloading 112 
using a backup copy 35 
master password 27 

( see also MASTERPW parameter) 
MASTERCATALOG parameter 
in CNVTCAT command 145 
in DEFINE command (defines user 
catalog) 51 
MASTERPW parameter 

in ALTER command 128 
in DEFINE command 
ALTERNATEINDEX 167 
CLUSTER 197 
PAGESPACE 233 
PATH 244 
USERCATALOG 259 
in EXPORTRA command 295 
in LISTCRA command 325 
in RESETCAT command 351 
nullifying 130 
MAXCC parameter 
in IF 360 
in SET 362 
maximum condition code 360,362 
memory ( see virtual storage) 
merging VSAM data sets 104 
migration of passwords 28 
MISCOMPARES messages 42,441 
mismatches between catalog and CRA 

records 40 
modal commands 5 

not allowed from TSO terminal 14 
MODEL parameter 

to define an alternate index 167 
to define a catalog 259 



167 



49 
49 



to define a cluster 197 
to define a page space 234 
to define a path 244 
to define a user catalog 
modeling 49 

alternate indexes 
clusters 197 

example 216 
data components 
index components 
page spaces 234 
paths 244 
user catalogs 259 
example 267 
modify sequence of execution 360 
modifying catalog information ( see ALTER 

command) 
MODULE subparameter (ALTER) 129 
moving data sets between 

systems 35,82 
moving entries 82 
moving user catalogs between 
systems 21,83 



name parameter (ALTER) ( see entryname 

parameter) 
NAME parameter 

in DEFINE command 

used to catalog a nonVSAM data 

set 223 
used to identify an alternate 

index 156 
used to identify a catalog 254 
used to identify a cluster 186 
used to identify a generation data 

group 218 
used to identify a page space 229 
used to identify a path 241 
in LISTCAT command 319 

example of output 414 
in LISTCRA command 325 

example of output 448,452 
names, generated 16 
names, generic (or qualified) 
in ALTER command 72 
in DEFINE command 46 

example 216 
in DELETE command 81 
in LISTCAT command 75 
naming 

clusters 186 
data components 186 
entry-sequenced data sets 186 
index components 186 
key-sequenced data sets 186 
master catalog 46 
page spaces 229 
paths 241 

user catalogs 46,218 
NE (not equal) 360 
NEWNAME parameter (ALTER) 128 
NEWNAME subparameter (IMPORT) 305 
NOCOMPARE parameter (LISTCRA) 325 

example of output 448,450 
NODESTAGEWAIT parameter 25 
in ALTER command 126 
in DEFINE command 
ALTERNATEINDEX 163 
catalog 258 
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CLUSTER 193 
USERCATALOG 258 
NOEMPTY parameter 

in ALTER command 126 
in DEFINE command 

used to define a generation data 
group 218 
NOERASE parameter 

in ALTER command 126 
in DEFINE command 

used to define an alternate 

index 163 
used to define a cluster 193 
in DELETE command 274 
in EXPORT command 287 
in IMPORT command 302 
not erasing data on a staging 
drive 25 
NOFORCE parameter 

in DELETE command 275 
in EXPORTRA command 295 
NOIGNORE parameter (RESETCAT) 351 
NOIMBED parameter (DEFINE) 
used to define an alternate 

index 165 
used to define a cluster 195 
NOINHIBITSOURCE parameter 

(EXPORT) 288 
NOINHIBITTARGET parameter 

(EXPORT) 288 
NOLIST parameter (CNVTCAT) 145 
NONE subparameter (EXPORTRA) 295 
NONE subparameter (RESETCAT) 350 
NONINDEXED parameter (DEFINE) 190 
NONSPANNED parameter (DEFINE) 203 
NONUNIQUEKEY parameter 
in ALTER command 129 
in DEFINE command 174 
nonVSAM data sets 

and the catalog's update 

password 30,54 
cataloging 64 
example 227 
copying 33 
deleting 77 

example of defining 227 
listing catalog entries for 75 
passwords for 30 
printing 114,328 
NONVSAM parameter 

in DEFINE command 64,223 
in DELETE command 272 
in LISTCAT command 318 
NOPURGE parameter 

in DELETE command 276 
in EXPORT command 288 
in IMPORT command 307 
NORECLAIM parameter 
in DEFINE command 

used to define an alternate 

index 169 
used to define a cluster 201 
NOREPLACE parameter (REPR0) 337 
NOREPLICATE parameter (DEFINE) 
used to define an alternate 

index 170 
used to define a cluster 201 
NOREUSE parameter 
in DEFINE command 

used to define an alternate 

index 170 
used to define a cluster 201 
in REPRO command 341 
normal output data set 11 



NOSAVRAC parameter 

in IMPORT command 307 
in IMPORTRA command 314 
NOSCRATCH parameter 
in DEFINE command 

used to define a generation data 
group 218 
in DELETE command 276 

catalog cleanup 30,276 
modified in ALTER command 132 
notation conventions vi 
NOSWAP parameter (DEFINE 
PAGESPACE) 229 
in DEFINE PAGESPACE command 235 
in DEFINE PAGESPACE example 258 
NOTUSABLE parameter (LISTCAT) 322 
NOUPDATE parameter 

in ALTER command 134 
in DEFINE command 246 
NOUPGRADE parameter 
in ALTER command 135 
in DEFINE command 176 
NOTRECOVERABLE parameter (DEFINE) 260 
NOWRITECHECK parameter 
in ALTER command 135 
in DEFINE command 
ALTERNATEINDEX 176 
CLUSTER 206 
USERCATALOG 262 
NULLIFY parameter (ALTER) 129 
NUMBERED parameter (DEFINE) 190 



objects (VSAM) 

in a data space 16,58 

space assignment to 58 
OBJECTS parameter 

in IMPORT command 303 

in IMPORTRA command 311 
OFF parameter (PARM) 363 
operator entering passwords 30 

( see also CODE parameter and ATTEMPTS 
parameter) 
optimizing the performance of catalog 

unload/reload 114 
optional allocation parameters 

for an alternate index 155 

for a cluster 185 
OR sign (|), in notation 

conventions vi 
order of catalog use 

ALTER 72 

BLDINDEX 69 

DEFINE 47 

DELETE 80 

LISTCAT 75 
ORDERED parameter (DEFINE) 

used to define an alternate 
i ndex 167 

used to define a cluster 198 
ORDERED subparameter (IMPORT) 305 
OS CVOLs (control volumes) 

converting to VSAM catalogs 86 

relationship to other catalogs 19 
OUTDATASET parameter 

in EXPORT command 287 

in IMPORT command 302 

in REPRO command 339 
OUTFILE parameter 

in BLDINDEX command 138 
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in CHKLIST command 142 
in EXPORT command 287 
in EXPORTRA command 292 
in IMPORT command 301 
in IMPORTRA command 314 
in LISTCAT command 322 
in LISTCRA command 325 
in PRINT command 331 
in REPRO command 339 
output data sets 

default for listing 12 
job control language for 12,444 
requirements 11 
overwriting ( see ERASE parameter) 
OWNER parameter 

in ALTER command 130 
in ALTER (NULLIFY) 130 
in DEFINE command 

note for TSO users 198 
used to define an alternate 

index 168 
used to define a catalog 260 
used to define a cluster 198 
used to define a generation data 

group 218 
used to define a nonVSAM data 

set 227 
used to define a page space 234 
used to define a path 245 
ownership bit in Format-4 DSCB 17 
ownership, VSAM volume 17 
removing 17 



PAGESPACE parameter 
in DEFINE command 

used to define a page 

space 57,228 
examples 238 
in DELETE command 272 
in LISTCAT command 318 
parameter abbreviations 5 
parameter organization (DEFINE 

command) 48 
parameter set 5 
parameters 

entry-types each ALTER parameter 

applies to 121 
keyword 5 
lists 6 

parentheses within 6 
positional 5 
separators and 6 
summary of 

for the definition of an alternate 

index 154 
for the" definition of a 

catalog 253 
for the definition of a 

cluster 184 
for the definition of a user 
catalog 253 
that apply only to key-sequenced 
clusters 186 
parentheses, in notational 

conventions vi 
PARM command 362 
password 

control 27 

( see also CONTROLPW parameter) 



for nonVSAM data set 30 
given by operator 30 
levels of authorization 27 
master 27 

( see also MASTERPW parameter) 
read 27 

( see also READPW parameter) 
update 27 

( see also UPDATEPW parameter) 
path 

defining 63,240 
deleting 77 

listing its catalog entry 75 
PATH parameter 

in DEFINE command 63,240 
in DELETE command 273 
in LISTCAT command 318 
PATHENTRY parameter (DEFINE) 241 
performance, optimizing VSAM f s 
catalog unload/reload 114 
staging/destaging with mass 
storage 25 
performance options information, 
speci fyi ng 
for an alternate index 62 
for a cluster 60 
PERMANENT parameter (EXPORT) 289 
plus sign 6 

PN, print chain option 363 
portable data sets 33^82 
position, key 5 

( see also KEYS parameter) 
positional parameters 5 
Preformatting control areas 32 
preventing duplicate names in a 

catalog 46 
preventive measures for protecting 

catalogs 39 
primary allocation ( see CYLINDERS 

parameter, RECORDS 
parameter, and TRACKS parameter) 
print chain options 363 
PRINT command 114,328 
examples 333 
format 328 
parameters 328 

optional parameters 329 
required parameters 328 
sample output from 329 
print graphics 363 
pri nt i ng 

catalog entries 75 
catalog recovery area contents 95 
data sets 114 

names of tape data sets open at 
checkpoint 116 
printing and copying, an example 

of 376 
processing program, invoking Access 

Method Services from 12 
prompting codes for operator entering 
passwords 30 
( see also CODE parameter and ATTEMPTS 
parameter) 
protecti ng 

( see also data integrity and data 

securi ty) 
alternate indexes 62 
catalogs 34 
clusters 32,60 
data 32 

data components 32 
index components 32 
paths 240 
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user catalogs 32 
protection and integrity parameters, 
speci fyi ng 
for an alternate index 62 
for a cluster 60 
protection parameters 60 
in ALTER command 119 
in DEFINE command 

used to define an alternate 

index 155 
used to define a catalog 253 
used to define a cluster 185 
used to define a page space 229 
used to define a path 240 
nullifying 129 
publications 
related v 
requi red i v 
PURGE parameter 

in DELETE command 276 
in EXPORT command 288 
in IMPORT command 307 



names 
72 
46 



qualified (generic) 

in ALTER command 

in DEFINE command 
example 216 

in DELETE command 81 

in LISTCAT command 75 
QN, print chain option 363 



23 



read integrity 30 
read password 27 

( see also READPW parameter) 
read-only access ( see READPW 

parameter) 
READPW parameter 

in ALTER command 130 
in DEFINE command 

for an alternate index 168 
for a catalog 260 
for a cluster 199 
for a page space 235 
for a path 245 
nullifying 130 
record 

( see also RECORDSIZE parameter) 
replacement, example of 380 
RECORDS parameter (DEFINE) 
used to define an alternate 

index 157 
used to define a catalog 254 
used to define a cluster 187 
used to define a data space 249 
used to define a page space 229 
RECORDSIZE parameter 
in ALTER command 131 
in DEFINE command 

to define an alternate index 168 
to define a cluster 199 
to define a data space 249 
recoverable* making the master 

catalog 39 
RECOVERABLE parameter (DEFINE) 260 



recovery, catalog 39,93 
other recovery methods 39 
the catalog recovery area 93 
recovery area ( see catalog recovery 

area) 
RECOVERY parameter (DEFINE) 
used to define an alternate 

index 173 
used to define a cluster 204 
regaining access to data 40 
regions sharing data 170,201 
RELATE parameter (DEFINE) 61,157 
related publications v 
reloading a catalog 112 
REMOVEVOLUMES parameter (ALTER) 131 

volume cleanup 38 
removing volumes 131 
removing VSAM ownership of a 

volume 18,38 
renaming data sets 

in ALTER command 71,119 
in IMPORT command 305 
reorganizing data sets 104 
REPLACE parameter (REPRO) 340 
REPLICATE parameter (DEFINE) 
used to define an alternate 

index 169 
used to define a cluster 201 
REPRO command 104,338 
catalog copying 110 
catalog unload/reload 112 

optimizing the performance of 114 
converting device of user 

catalog 104 
example 343 
format 338 
parameters 338 

optional parameters 339 
requi red -parameters 338 
required publications iv 
requirements, storage 

VSAM catalog 51 
reserving volumes ( see CANDIDATE 
parameter, VOLUME parameter, and 
ADDVOLUMES parameter) 
reset condition codes 362 
RESETCAT command 350 
examples 353 
format 350 
function 98 
JCL Requirements 102 
multivolume data sets 101 
parameters 350 

optional parameter 350 
required parameter 350 
reference summary 471 
requirements 100 
WORKFILE Space Requirements 101 
respecifying attributes 99,119 
Resource Access Control Facility 
(RACF) 31 
when moving entries 82 
in EXPORTRA 97 
in ALTER 129 
RESTORE program, IEHDASDR 35 
restoring a cluster's end-of-file 

values 91 
restoring catalog entries after system 
fai lure 93 
catalog recovery area contents 93 

li sting the 94 
copying a catalog entry from the 

catalog recovery area 95 
examples of 315 
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procedure for 93 
resetting catalog entries 98 
restoring the catalog entry that was 
obtained using the EXPORTRA 
command 97 
retention date for data set 

( see also FOR parameter and TO 

parameter) 
nullifying 130 



o 
RET 
re 



ter) 
30 



nuniTying i^u 
overriding ( see PURGE parame 
TENTION parameter (ALTER) 1 
. ^usable data sets 201 
REUSE parameter 
in DEFINE command 

used to define an alternate 

index 170 
used to define a cluster 201 
in REPRO command 341 
RN, print chain option 363 
rules of continuation 7 



SAM data sets 
cataloging 223 
converting 104 
copying 104 
deleting 77 
listing catalog entries 
printing 114 

SAM to VSAM conversion 1 

SAVRAC parameter 

in IMPORT command 307 
in IMPORTRA command 31 

SCRATCH parameter 
in DEFINE command 

used to define a gene 
group 218 
in DELETE command 276 
modified in ALTER comma 

searching catalogs, order 
with the ALTER command 
with the BLDINDEX comma 
with the DEFINE command 
with the DELETE command 
with the LISTCAT comman 

secondary allocation ( see 
parameter, RECORDS param 
TRACKS parameter) 
amount for the catalog 

secondary extents, access 
to 33 

securi ty 

authorization routine 
bits in Format-1 DSCB 
passwords 27 

separators 6 

sequence of execution, 
controlling 5,359 

sequential data set, conv 

SEQUENTIALDUMP parameter 
(LISTCRA) 325 

SET command 362 
examples 364 
format 362 

set condition codes 362 

setting up the master cat 

SHAREOPTIONS parameter 
in ALTER command 132 
in DEFINE command 

used to define an alt 



for 75 
04 



ration data 



nd 132 
of 
72 
nd 69 
47 
80 
d 75 

CYLINDERS 
eter, and 

56 
i bi 1 i ty 



31 
17 



erting 104 



alog 20 



ernate 



index 170 
used to define a cluster 201 
sharing data 

options modified in ALTER 

command 132 
specified in DEFINE command 170,201 
SKIP parameter 

in PRINT command 330 
in REPRO command 340 
slashes 5,10 

SN, print chain option 363 
sort parameters (BLDINDEX) 139 
sort workfiles for building an 
alternate index 67 
DD statements that describe the 69 
estimating space requirements 
for 67 
space allocation for the catalog 

recovery area (CRA) 57 
space assignment 
to a catalog 51 

to a catalog recovery area (CRA) 57 
to VSAM objects 57 
space estimates 
for a catalog 51 
example of 264 
worksheet for 55 
for the BLDINDEX sort workfiles 67 
for the RESETCAT work file 101 
SPACE parameter 

in DEFINE command 57,249 
in DELETE command 273 
in LISTCAT command 319 
example of output 421 
space, data 

allocating 57,249 

defining 57,249 

deleting 77,273 

extending 56 

for a catalog recovery area 

(CRA) 57 
space allocation in a catalog's 

data space 57 
VSAM objects in a 58 
SPANNED parameter (DEFINE) 203 
spanned records 203 
specifying alternate index 
information 61 
descriptive information 62 
performance options information 62 
protection and integrity 
information 62 
specifying cluster information 59 
descriptive information 59 
performance options information 60 
protection and integrity 
information 60 
SPEED parameter (DEFINE) 

used to define an alternate 

index 173 
used to define a cluster 204 
spreading data sets over volumes ( see 

KEYRANGES parameter) 
STAGE parameter 25 

in ALTER command 133 
in DEFINE command 

used to define an alternate 

index 173 
used to define a cluster 204 
staging attributes 25 

( see als o BIND, CYLINDERFAULT, 
DESTAGEWAIT, NODESTAGEWAIT, and 
STAGE parameters) 
staging drive 25 
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staging from mass storage 25 
starting location 

in PRINT command 330 
in REPRO command 340 
STEPCAT catalog 110 

DD statement for 21,110 
order of catalog use 
ALTER 72 
BLDINDEX 69 
DEFINE 47 
. DELETE 80 
LISTCAT 75 
stop testing 363 
stopping location 

in PRINT command 331 
in REPRO command 341 
storage requirements 

VSAM catalog 51 
STRING subparameter (ALTER) 129 
structure of commands 6 
SUBALLOCATION parameter (DEFINE) 
used to define an alternate 

index 174 
used to define a cluster 205 
summary of Access Method Services 

operations 1 
summary of amendments vii 
SWAP parameter 

in DEFINE PAGESPACE command 235 
in DEFINE PAGESPACE example 239 
syntax 5 
system failure, restoring catalog 

entries after 93 
system's catalogs, example of defining 

the 366 
SYS1. NUCLEUS, pointer to master 
catalog in 20 



TABLE parameter (PARM) 363 
tape data sets 

for backup copies 112 

for transporting data 32 

open at checkpoint 116 
tape volumes mounted at 

checkpoint 116 
temporary exportation 83 
TEMPORARY parameter (EXPORT) 289 
terminate processing 360 
terminator, command 8 
TEST parameter (PARM) 363 
THEN clause, in IF-THEN-ELSE command 

sequence 360 
Time Sharing Option (TSO) 23 

abbreviated LISTCAT 
listings 319,436 

invoking Access Method Services from 
a terminal 14 
timestamp updating 15 
TN, print chain option 363 
TO parameter 

in ALTER command 134 

in DEFINE command 



used to 


def i ne 


an alternate 


i ndex 


174 




used to 


def i ne 


a catalog 261 


used to 


def i ne 


a cluster 205 


used to 


def i ne 


a generation data 


group 


218 




used to 


def i ne 


a nonVSAM data 



5 
US 
US 

TOADDR 
in P 
i n R 

TO KEY 
in P 
in R 

TONUMB 
in P 
in R 

TRACE 

traci n 

TRACKS 
used 
i nd 
used 
used 
used 
used 

Transl 

transp 
syste 

TSO (T 

abbr 

lis 

i nvo 

a t 

types 



et 227 

to define a page space 235 



ed 



d to define a page spaci 

ed to define a path 246 

ESS parameter 

RINT command 331 

EPRO command 341 

parameter 

RINT command 331 

EPRO command 341 

ER parameter 

RINT command 331 

EPRO command 341 

parameter (PARM) 363 

g outputs 363 
parameter (DEFINE) 
to define an alternate 

ex 157 
to define a catalog 254 
to define a cluster 187 
to define a data space 249 

I to define a page space 229 

ate Table, device type 414 

sorting data sets between 

ms 32,82 

ime Sharing 1 Option) 23 

eviated LISTCAT 

tings 319,436 

king Access Method Services from 

erminal 14 

of commands 4 



127 



underlining, in notation 

conventions vi 
UNINHIBIT parameter (ALTER) 
unique data set 
defining 205 
space for 45 
UNIQUE parameter (DEFINE) 

used to define an alternate 

index 174 
used to define a cluster 205 
UNIQUEKEY parameter 
in ALTER command 134 
in DEFINE command 174 
unload/reload, catalog 112 

optimizing the performance of 
unloading a catalog 112 
UNORDERED parameter (DEFINE) 
used to define an alternate 

index 167 
used to define a cluster 198 
UNORDERED subparameter (IMPORT) 
update access 27 * 
UPDATE parameter 
in ALTER command 
in DEFINE command 
update password 27 

nonVSAM data sets and the catalog's 

update password 54 
( see also UPDATEPW parameter) 
UPDATEPW parameter 
in ALTER command 
in DEFINE command 
ALTERNATEINDEX 
catalog 261 
CLUSTER 206 
PAGESPACE 236 
PATH 247 
USERCATALOG 261 



114 



305 



134 
246 



135 
174 
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nulli fyi ng 130 
updating a backup copy of a 

catalog 35 
updating a data set's end-of-file 

information 91 
updating timestamps 18 
UPGRADE parameter 

in ALTER command 135 
in DEFINE command 176 
uppercase, in notation conventions vi 
USAR ( see usei — security authorization 

record) 
user catalog 

( see also master catalog) 
allocating 51 
altering 71 
backing up 35,112 
calculating space for 51,54 
cataloging nonVSAM data sets 64 
connecting to master catalog 

(IMPORT). 83 
creating a 253 
examples 264 
defined on mass storage volume 51 
deleting 77 
disconnecting from master catalog 

(EXPORT) 83 
exporting 83 
importing 82 
JCL 21,46 
1 i st i ng 75 
order of use 
ALTER 72 
BLDINDEX 69 
DEFINE 47 
DELETE 80 
LISTCAT 75 
preventing duplicate names 46 
protecting 34 
relationship to master 

catalog 20,51 
reloading 112 
structure 19 
transporting 38 
unloading 112 
using a backup copy 35 
volume portability 82 
USERCATALOG parameter 
in DEFINE command 253 
in DELETE command 273 
in LISTCAT command 319 
user's program, invoking Access Method 

Services from a 13 
user's I/O routines 472 
using generic (qualified) names for 

cataloged objects 21 
using one object as a model for 

another object 49 
using passwords to authorize access to 

data 27 
using the catalog recovery area 93 
use i — securi ty-authori zati on record 
(USAR) 
in ALTER command 124 
in DEFINE command 
ALTERNATEINDEX 160 
catalog 254 
CLUSTER 190 
PAGESPACE 230 
PATH 242 
USERCATALOG 254 
user — securi ty-veri f i cati on routi ne 
(USVR) 31 
in ALTER command 124 



in DEFINE Command 
ALTERNATEINDEX 160 
catalog 254 
CLUSTER 190 
PAGESPACE 230 
PATH 242 
USERCATALOG 254 
USVR ( see user=securi ty-veri fi cat i on 
routi ne) 



VERIFY command 357 

example 358 

format 357 

parameters 357 
volser (see REMOVEVOLUMES, VOLUME, and 

VOLUMES parameters) 
volume 

allocating the 58 

data spaces on a 57 

dumping a 35 

identifying the catalog's 54 
volume cleanup 36,73 
volume mounting required during 

DELETE 77 
volume ownership, VSAM 17 

removing it 36 
VOLUME parameter 

in DEFINE command 

used to define a catalog 254 

in LISTCAT command 319 
example of output 419 
volume, mass storage 25 
volume serial number, changing the 37 
VOLUMES parameter (DEFINE) 

used to define an alternate 
index 159 



catalog 254 
cluster 188 
data space 251 
nonVSAM data 



used to define 

used to define 

used to define 

used to define 
set 224 

used to define a page space 230 
VOLUMES subparameter 

in IMPORT command 306 

in IMPORTRA command 312 
volumes, tape, mounted at 

checkpoi nt 116 
VSAM catalog ( see catalog, master 

catalog, and user catalog) 
VSAM catalog cleanup 38,275 
VSAM data sets, example of 

defining 210 
VSAM to SAM conversion 104 
VSAM volume cleanup 36,73 
VSAM volume ownership 17 

removing it 38 
VTOC (volume table of contents) 17,38 



WORKCAT parameter (RESETCAT) 351 
WORKFILE parameter (RESETCAT) 352 
Work file space requirements 

(RESETCAT) 101 
WORKFILES parameter (BLDINDEX) 139 
write access (see UPDATEPW parameter) 
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write integrity 31 

write operation, verification 

WRITECHECK parameter) 
WRITECHECK parameter 
in ALTER command 135 
in DEFINE command 
ALTERNATEINDEX 176 
CLUSTER 206 



( see 



USERCATALOG 262 



123 
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